# netbox.dadl -- NetBox REST API (v4.x)
# DADL backend for ToolMesh
#
# Domain Notes for LLM consumers:
# - NetBox is an open-source DCIM (Data Center Infrastructure Management) and IPAM
#   (IP Address Management) tool. It models the physical and logical network.
# - Objects are identified by numeric IDs (not UUIDs). Use ?brief=true for compact responses.
# - All list endpoints support filtering: ?name=foo, ?site=site-slug, ?status=active,
#   ?tag=mytag, ?q=search-term. Negation: ?status__n=decommissioned.
# - Lookup expressions on most filter params: __n (not), __ic (contains, case-insensitive),
#   __nic, __ie (iexact), __isw (starts-with), __iew (ends-with), __empty, __gt, __gte, __lt, __lte.
# - Ordering: ?ordering=name (asc), ?ordering=-created (desc).
# - Field selection: ?fields=id,name,status or ?omit=config_context (v4.5.2+).
# - Related objects are set by ID (e.g. "site": 5) or nested unique set
#   (e.g. "site": {"name": "DC1"}).
# - "Slug" fields are URL-safe identifiers (lowercase, hyphens). Most models have name + slug.
# - Bulk operations: POST/PATCH/DELETE accept arrays. All-or-none — one error aborts all.
# - Tags are many-to-many: pass as array of {name, slug, color} or {id} objects.
# - Custom fields: stored under "custom_fields" dict on each object.
# - Status values vary per model: "active", "planned", "staged", "decommissioning", etc.
# - A "prefix" in IPAM is a CIDR block (e.g. 10.0.0.0/24). A "VRF" is a routing domain.
#   Route-targets (e.g. "65000:100") attach to VRFs as import_targets/export_targets for L3VPN.
# - 1:1 NAT pairs: set nat_inside (writable) on the OUTSIDE address; nat_outside is the
#   read-only reverse view on the inside address.
# - A "VLAN" has a numeric vid (1-4094) and belongs to a VLAN group and optional site.
#   VLAN translation policies define 1:1 local-to-remote VID rewrites.
# - FHRP (First Hop Redundancy Protocol) groups model virtual IP failover (VRRP, HSRP, CARP, GLBP).
#   Each group has a protocol + group_id. Assign interfaces via fhrp-group-assignments with priority 0-255.
# - Devices have components: interfaces, console-ports, console-server-ports, power-ports,
#   power-outlets, front-ports, rear-ports, module-bays, device-bays, inventory-items.
#   Each component-type has a matching *-template on the device-type that is instantiated
#   when a device is created. Likewise module-types carry their own component templates.
# - Modules are hardware sub-units installed into module-bays. Inserting a module auto-creates
#   its components from the module-type templates; removing it deletes them.
# - Virtual chassis (VC) groups multiple physical devices into one logical device with a master.
#   Set virtual_chassis + vc_position + vc_priority on member devices via update_device.
# - Devices carry primary_ip4/primary_ip6 and oob_ip (out-of-band management, e.g. BMC/iDRAC/iLO).
#   All three are set via update_device and require the IP to already be assigned to an
#   interface of that device (or NAT-linked to one) -- otherwise NetBox rejects with HTTP 400.
# - Virtual device contexts (VDCs) split one physical device into multiple logical contexts
#   (Cisco Nexus model). Interfaces can belong to one or more VDCs.
# - Power model: power-panel -> power-feed -> power-port (device side) and power-outlet
#   (downstream sockets, e.g. on a PDU). Voltage is signed: -48 means -48VDC.
# - Cables connect any two terminations. Endpoint object_types are polymorphic:
#   dcim.interface, dcim.frontport, dcim.rearport, dcim.consoleport, dcim.consoleserverport,
#   dcim.powerport, dcim.poweroutlet, dcim.powerfeed, circuits.circuittermination.
#   /dcim/<port>/{id}/trace/ walks the full path through patch panels to the far end.
# - Virtual machines live in clusters and have interfaces and virtual-disks. VM types
#   (NetBox 4.2+) normalize hardware models (e.g. AWS "m5.xlarge").
# - Circuits model carrier services. Virtual circuits (NetBox 4.2+) ride on top of provider
#   networks and define logical end-to-end paths with terminations on physical interfaces.
# - VPN: tunnels carry an encapsulation (ipsec-tunnel/ipsec-transport/ip-ip/gre/wireguard/...).
#   For IPSec, bind an ipsec_profile (= ike_policy + ipsec_policy + mode). Add per-side
#   tunnel-terminations with role peer/hub/spoke. L2VPN (VPLS/VXLAN/EVPN) terminations
#   attach VLANs, interfaces, or VRFs to an L2VPN service.
# - Tenancy: contact-assignments link contacts to any model with the ContactsMixin
#   (devices, racks, circuits, prefixes, VMs, ...) with priority (primary/secondary/tertiary/inactive).
# - Extras hosts cross-cutting features: tags, custom-fields, journal-entries, config-contexts,
#   config-templates (Jinja2 rendered with config-context data), webhooks (HTTP delivery),
#   event-rules (bind webhook/script/notification-group to a model + event type),
#   scripts (POST /extras/scripts/{id}/ to run -- returns a job, poll /core/jobs/),
#   export-templates, saved-filters, custom-links, bookmarks, notifications, image-attachments,
#   dashboard (singleton GET/PATCH for the current user).
# - Core hosts platform resources: data-sources (git/S3 sync for templates/scripts/contexts,
#   POST /core/data-sources/{id}/sync/ enqueues a job), data-files, jobs (async work status),
#   object-types (Django ContentTypes -- used in polymorphic object_type fields).
# - Users app exposes users, groups, object-permissions (per-model + per-action grants with
#   optional ORM-style constraints), and tokens. The token 'key' is returned ONLY on create
#   (one-shot); subsequent GETs do not expose it. POST /users/tokens/provision/ bootstraps a
#   token from username+password.
# - The API root at /api/ lists all available app endpoints. Swagger UI at /api/schema/swagger-ui/.

spec: "https://dadl.ai/spec/dadl-spec-v0.1.md"

credits:
  - "Dunkel Cloud GmbH -- maintainer"

source_name: "NetBox REST API"
source_url: "https://netboxlabs.com/docs/netbox/integrations/rest-api/"
date: "2026-08-15"

backend:
  name: netbox
  type: rest
  version: "2.2"
  # base_url is intentionally omitted -- must be provided via backends.yaml url field,
  # because each deployment has its own NetBox instance address.
  description: "NetBox DCIM/IPAM API -- full v4 coverage: sites, racks, devices, modules, interfaces, cables, power, IPAM (prefixes, IPs, VLANs, VRFs, route-targets, VLAN translation), virtualization, circuits (including virtual circuits), tenants, contacts, VPN (IKE/IPSec/L2VPN), wireless, extras (webhooks, event-rules, scripts, config-templates, bookmarks, notifications), users/permissions/tokens, and core data sources & jobs"

  auth:
    type: bearer
    credential: netbox_token
    # NetBox v2 tokens: "Authorization: Bearer nbt_xxx"
    # NetBox v1 tokens: "Authorization: Token xxx" (legacy)

  defaults:
    headers:
      Content-Type: application/json
      Accept: application/json
    pagination:
      strategy: offset
      request:
        cursor_param: offset
        limit_param: limit
        limit_default: 50
      response:
        next_cursor: "$.next"
        has_more: "$.next != null"
      behavior: expose
      max_pages: 20
    errors:
      format: json
      message_path: "$.detail"
      retry_on: [429, 502, 503, 504]
      retry_strategy:
        max_retries: 3
        backoff: exponential
        initial_delay: 1s
      terminal: [400, 401, 403, 404]
      rate_limit:
        header: X-RateLimit-Remaining
        retry_after_header: X-RateLimit-Reset
    response:
      result_path: "$.results"
      max_items: 500

  coverage:
    endpoints: 608
    total_endpoints: 620
    percentage: 98
    focus: >
      DCIM full v4: sites, site-groups, regions, locations,
      racks (with elevation, roles, types, reservations), manufacturers,
      device-types, device-roles, platforms, devices, modules, module-types,
      module-bays, device-bays, virtual-chassis, virtual-device-contexts,
      inventory-items, inventory-item-roles, interfaces, cables,
      cable-terminations, all port types (console, console-server, power,
      power-outlet, front, rear) with trace/paths actions, power-panels,
      power-feeds, mac-addresses, connected-device lookup, and the
      complete component-template family.
      IPAM full v4: prefixes (with available-prefixes/available-ips),
      ip-addresses, ip-ranges (with available-ips), vlans, vlan-groups
      (with available-vlans), vrfs, route-targets, aggregates, rirs, asns,
      asn-ranges (with available-asns), roles, services, service-templates,
      vlan-translation-policies, vlan-translation-rules, fhrp-groups,
      fhrp-group-assignments.
      Virtualization full v4: clusters, cluster-types, cluster-groups,
      virtual-machines, virtual-machine-types, vm-interfaces, virtual-disks.
      Tenancy full v4: tenants, tenant-groups, contacts, contact-roles,
      contact-groups, contact-assignments.
      Circuits full v4: providers, provider-accounts, provider-networks,
      circuit-types, circuits, circuit-terminations (with paths),
      circuit-groups, circuit-group-assignments, virtual-circuits,
      virtual-circuit-types, virtual-circuit-terminations.
      Wireless full v4: wireless-lan-groups, wireless-lans, wireless-links.
      VPN full v4: tunnel-groups, tunnels, tunnel-terminations, ike-proposals,
      ike-policies, ipsec-proposals, ipsec-policies, ipsec-profiles, l2vpns,
      l2vpn-terminations.
      Extras: tags, custom-fields, custom-field-choice-sets, custom-links,
      saved-filters, export-templates, journal-entries, object-changes,
      config-contexts, config-templates (+render), webhooks, event-rules,
      scripts (+run), bookmarks, notifications, notification-groups,
      subscriptions, image-attachments, dashboard.
      Users: users, groups, permissions, tokens (+provision).
      Core: data-sources (+sync), data-files, jobs, object-types,
      background-queues/workers/tasks.
    missing: >
      Read-only listing of background-tasks with action endpoints
      (delete/requeue/enqueue/stop) -- rarely used outside debugging.
      Plugin-specific endpoints under /api/plugins/ -- those depend on
      installed plugins and are out of scope for a general DADL.
      table-configs, config-context-profiles, tagged-objects, and the
      authentication-check endpoint -- minor utility endpoints.
      Bulk update/delete on list endpoints (PUT/PATCH/DELETE on collections)
      -- prefer per-object operations in Code Mode.
    last_reviewed: "2026-08-15"

  setup:
    credential_steps:
      - "Log in to your NetBox instance as an admin user"
      - "Navigate to your user profile (top-right) -> API Tokens"
      - "Click 'Add a token' and configure permissions"
      - "For full access: leave 'Write enabled' checked, no IP restrictions"
      - "Copy the generated token -- it is shown only once (v2 tokens)"
      - "v2 tokens start with 'nbt_' -- enter only the token value, ToolMesh adds the auth header automatically"
    env_var: CREDENTIAL_NETBOX_TOKEN
    backends_yaml: |
      - name: netbox
        transport: rest
        dadl: netbox.dadl
        url: "https://netbox.example.com/api"
    required_scopes:
      - "Read/Write token for full functionality"
    optional_scopes:
      - "Read-only token for safe exploration"
    docs_url: "https://netboxlabs.com/docs/netbox/integrations/rest-api/"
    notes: "The url in backends.yaml must include /api (e.g. https://netbox.example.com/api). Enter only the raw token value (e.g. nbt_xxx) -- ToolMesh handles the Authorization header. Swagger docs at /api/schema/swagger-ui/."

  hints:
    list_devices:
      filtering: "Filter by site, rack, role, manufacturer, model, status, tag, etc. E.g. ?site=dc1&status=active&role=server"
      brief: "Use ?brief=true for compact results with just id, url, display, name"
      vc_filter: "?virtual_chassis_id=N returns members of a VC. ?vc_position to filter by stack member position."
    list_ip_addresses:
      filtering: "Filter by address, vrf, interface, device, vm, status, role, tenant"
      parent_lookup: "?parent=10.0.0.0/16 returns all IPs within that prefix"
      assigned: "Set ?assigned=true / ?assigned=false to find IPs bound or unbound to interfaces"
    list_prefixes:
      filtering: "?within=10.0.0.0/8 returns all sub-prefixes. ?contains=10.0.1.50 finds the prefix."
      available: "GET /api/ipam/prefixes/{id}/available-ips/ shows free IPs. POST same path to claim one atomically."
      child_carve: "claim_prefix POSTs to /prefixes/{id}/available-prefixes/ to carve a new child prefix at a specified mask"
    list_interfaces:
      filtering: "?device=hostname or ?device_id=123. ?type=1000base-t for specific types."
      lag: "lag_id filters interfaces by their LAG parent. Use ?type=lag to find the parent itself."
      vdc: "?vdc_id filters interfaces belonging to a specific virtual device context"
    update_device:
      oob_ip_workflow: "To set an out-of-band management IP: 1) ensure a mgmt interface exists (create_interface, e.g. mgmt_only=true), 2) create_ip_address with assigned_object_type='dcim.interface' + assigned_object_id, 3) update_device with oob_ip=<ip id>. Same flow applies to primary_ip4/primary_ip6."
      nullable_fks: "primary_ip4, primary_ip6, oob_ip, virtual_chassis are nullable -- pass JSON null to clear."
      vc_membership: "Join a virtual chassis with virtual_chassis=<id> + vc_position (unique per VC) + vc_priority. Leave it by passing virtual_chassis=null."
    update_interface:
      mac_workflow: "MAC addresses are separate objects since NetBox 4.x: create_mac_address({mac_address, assigned_object_type:'dcim.interface', assigned_object_id}) first, then set primary_mac_address=<id> on the interface. The interface field mac_address is read-only."
      nullable_fks: "untagged_vlan, lag, parent, bridge, vrf, primary_mac_address are nullable -- pass JSON null in the PATCH body to clear them. Omitting the key leaves the current value unchanged."
      nullable_choices: "mode and duplex are nullable -- pass null to clear (mode=null reverts to access-mode default; duplex=null lets the driver auto-negotiate)."
      m2m_clear: "tagged_vlans, wireless_lans, and tags are many-to-many arrays -- pass [] (empty array) to detach all; pass null is not the right idiom for M2M."
      wireless_lans: "Array of wireless_lan object IDs. Only meaningful when type=wireless-ac/n/ax/... (i.e. the interface is a wireless interface)."
      mode_vlan_dependency: "Setting mode=null while untagged_vlan or tagged_vlans is still populated will fail validation. Clear the VLAN assignments in the same PATCH or before."
    list_vlans:
      filtering: "?vid=100, ?group=my-group, ?site=dc1"
      available: "GET /api/ipam/vlan-groups/{id}/available-vlans/ lists free VIDs within a group; POST to claim"
    create_device:
      required: "name, role (id or nested), device_type (id or nested), site (id or nested)"
      note: "After creating a device, interfaces are auto-created from the device type template"
      vc_membership: "To stack into a virtual chassis, set virtual_chassis (id) + vc_position (1..N) + vc_priority"
    create_virtual_machine:
      required: "name, cluster (id or nested)"
      type: "NetBox 4.2+ supports virtual_machine_type as a normalized model -- pass as integer id"
    create_ip_address:
      required: "address (CIDR notation, e.g. '10.0.0.1/24')"
      assign: "Set assigned_object_type='dcim.interface' and assigned_object_id=<id> to bind to an interface"
      vminterface: "For VM interfaces use assigned_object_type='virtualization.vminterface'"
      nat: "1:1 NAT: set nat_inside=<inside ip id> on the OUTSIDE address. nat_outside is read-only (reverse view) and cannot be written."
    create_service:
      netbox_4x: "NetBox 4.x replaced device/virtual_machine with GenericForeignKey: use parent_object_type ('dcim.device' or 'virtualization.virtualmachine') + parent_object_id"
      custom_fields: "Pass custom_fields as key-value object, e.g. {prom_http_url: 'http://...:9090/metrics'}"
    create_custom_field_choice_set:
      extra_choices: "Array of [value, label] pairs, e.g. [['tcp','TCP'],['udp','UDP']]"
    create_cable:
      both_ends: "A cable needs a_terminations AND b_terminations -- each is an array of {object_type, object_id}"
      object_types: "Endpoint object_type values: dcim.interface, dcim.frontport, dcim.rearport, dcim.consoleport, dcim.consoleserverport, dcim.powerport, dcim.poweroutlet, dcim.powerfeed, circuits.circuittermination"
    create_module:
      auto_components: "Installing a module auto-creates its components (interfaces, ports) from module-type templates. Removing it deletes them."
    create_virtual_chassis:
      member_assignment: "Build the VC first, then PATCH each member device with virtual_chassis=<id>, vc_position=N, vc_priority=N"
    create_rack_reservation:
      units_array: "units is an array of unit numbers (top-down) e.g. [38,39,40] reserves U38-U40"
    create_power_feed:
      voltage_signs: "voltage is signed; -48 means -48VDC. amperage is in amps. max_utilization is percent (1-100)."
    create_tunnel:
      profile_for_ipsec: "For IPSec tunnels, set encapsulation='ipsec-tunnel' (or ipsec-transport) and bind ipsec_profile"
      add_terminations: "After creating the tunnel, add create_tunnel_termination for each side with role peer/hub/spoke"
    create_l2vpn:
      identifier_range: "identifier is the L2VPN-wide ID (e.g. VNI for VXLAN). Per-type recommended ranges in NetBox docs."
      bind_terminations: "Add l2vpn-terminations to attach VLANs, interfaces, or VRFs to the L2VPN service"
    create_ike_policy:
      proposals_order: "proposals is ordered: first match wins during IKE negotiation"
      preshared_key: "preshared_key is stored encrypted; only readable by users with auth.view_token permission"
    create_event_rule:
      action_target: "action_object_type + action_object_id point at the target: extras.webhook for HTTP callbacks, extras.script for scripts, extras.notificationgroup for in-app notifications"
      conditions_dsl: "conditions is JSON DSL: {and: [{attr: 'status', value: 'active'}, ...]}"
    run_script:
      job_polling: "Returns a Job object with id; poll /core/jobs/{id}/ until status is 'completed', 'errored', or 'failed'"
      commit: "commit=false runs a dry-run that rolls back DB changes -- useful for validation"
    sync_data_source:
      async: "Returns immediately with a job ID; sync runs in the background. Watch /core/jobs/{id}/ to see status."
    create_webhook:
      decoupled: "NetBox 4.0+ decoupled webhooks from triggers. Webhooks now only define HTTP delivery -- bind to events via event-rules."
      body_template: "Custom Jinja2 body templates use {{ event }}, {{ model }}, {{ data }}, {{ snapshots }}, {{ username }}, {{ request_id }}"
    create_token:
      one_shot_key: "The 'key' field is returned ONLY on the create response. Save it immediately; subsequent GETs do not return it."
      bootstrap: "provision_token (POST /users/tokens/provision/) lets a user obtain their first token with username+password"
    create_contact_assignment:
      polymorphic: "object_type accepts any model with the ContactsMixin -- e.g. dcim.device, dcim.rack, circuits.circuit, virtualization.virtualmachine, ipam.prefix"
    get_rack_elevation:
      svg: "?render=svg returns image/svg+xml; default is application/json. ?face=rear shows the rear face."
    get_connected_device:
      params_required: "Both peer_device (name) and peer_interface (name) must be supplied; returns 404 if not connected via cable"

  tools:

    # =========================================================================
    # DCIM -- Sites & Locations
    # =========================================================================

    list_sites:
      method: GET
      path: /dcim/sites/
      access: read
      description: "List all sites (data centers, offices, PoPs)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        status: { type: string, in: query, description: "planned, staging, active, decommissioning, retired" }
        region: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query, description: "Full-text search" }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }
        ordering: { type: string, in: query }

    get_site:
      method: GET
      path: /dcim/sites/{id}/
      access: read
      description: "Get a specific site"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_site:
      method: POST
      path: /dcim/sites/
      access: write
      description: "Create a new site"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        status: { type: string, in: body, description: "planned, staging, active, decommissioning, retired" }
        region: { type: integer, in: body }
        tenant: { type: integer, in: body }
        facility: { type: string, in: body }
        description: { type: string, in: body }
        physical_address: { type: string, in: body }
        shipping_address: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    update_site:
      method: PATCH
      path: /dcim/sites/{id}/
      access: write
      description: "Update a site"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        status: { type: string, in: body }
        region: { type: integer, in: body }
        tenant: { type: integer, in: body }
        facility: { type: string, in: body }
        physical_address: { type: string, in: body }
        shipping_address: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    delete_site:
      method: DELETE
      path: /dcim/sites/{id}/
      access: dangerous
      description: "Delete a site"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_regions:
      method: GET
      path: /dcim/regions/
      access: read
      description: "List all regions (geographic grouping of sites)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_region:
      method: POST
      path: /dcim/regions/
      access: write
      description: "Create a region"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_region:
      method: GET
      path: /dcim/regions/{id}/
      access: read
      description: "Get a specific region"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_region:
      method: PATCH
      path: /dcim/regions/{id}/
      access: write
      description: "Update a region"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_region:
      method: DELETE
      path: /dcim/regions/{id}/
      access: dangerous
      description: "Delete a region"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_locations:
      method: GET
      path: /dcim/locations/
      access: read
      description: "List locations within sites (rooms, floors, cages)"
      params:
        site: { type: string, in: query }
        site_id: { type: integer, in: query }
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_location:
      method: POST
      path: /dcim/locations/
      access: write
      description: "Create a location within a site"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        site: { type: integer, in: body, required: true }
        parent: { type: integer, in: body }
        status: { type: string, in: body, description: "planned, staging, active, decommissioning, retired" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_location:
      method: GET
      path: /dcim/locations/{id}/
      access: read
      description: "Get a specific location"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_location:
      method: PATCH
      path: /dcim/locations/{id}/
      access: write
      description: "Update a location"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        site: { type: integer, in: body }
        parent: { type: integer, in: body }
        tenant: { type: integer, in: body }
        facility: { type: string, in: body }
        status: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_location:
      method: DELETE
      path: /dcim/locations/{id}/
      access: dangerous
      description: "Delete a location"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Site Groups
    # =========================================================================

    list_site_groups:
      method: GET
      path: /dcim/site-groups/
      access: read
      description: "List site groups (hierarchical grouping of sites, orthogonal to regions)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        parent: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_site_group:
      method: GET
      path: /dcim/site-groups/{id}/
      access: read
      description: "Get a specific site group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_site_group:
      method: POST
      path: /dcim/site-groups/
      access: write
      description: "Create a site group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_site_group:
      method: PATCH
      path: /dcim/site-groups/{id}/
      access: write
      description: "Update a site group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_site_group:
      method: DELETE
      path: /dcim/site-groups/{id}/
      access: dangerous
      description: "Delete a site group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Racks
    # =========================================================================

    list_racks:
      method: GET
      path: /dcim/racks/
      access: read
      description: "List all racks"
      params:
        site: { type: string, in: query }
        site_id: { type: integer, in: query }
        location: { type: string, in: query }
        name: { type: string, in: query }
        status: { type: string, in: query }
        role: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_rack:
      method: GET
      path: /dcim/racks/{id}/
      access: read
      description: "Get a specific rack"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_rack:
      method: POST
      path: /dcim/racks/
      access: write
      description: "Create a rack"
      params:
        name: { type: string, in: body, required: true }
        site: { type: integer, in: body, required: true }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        location: { type: integer, in: body }
        u_height: { type: integer, in: body, description: "Rack height in units (default 42)" }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_rack:
      method: PATCH
      path: /dcim/racks/{id}/
      access: write
      description: "Update a rack"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        site: { type: integer, in: body }
        location: { type: integer, in: body }
        role: { type: integer, in: body }
        u_height: { type: integer, in: body, description: "Rack height in units (default 42)" }
        tenant: { type: integer, in: body }
        status: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_rack:
      method: DELETE
      path: /dcim/racks/{id}/
      access: dangerous
      description: "Delete a rack"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_rack_elevation:
      method: GET
      path: /dcim/racks/{id}/elevation/
      access: read
      description: >
        Get rack elevation -- returns the rack units with installed devices.
        Use ?render=svg for a graphical SVG rendering, default is JSON list of units.
      params:
        id: { type: integer, in: path, required: true }
        face: { type: string, in: query, description: "front (default) or rear" }
        render: { type: string, in: query, description: "json (default) or svg" }
        unit_width: { type: integer, in: query }
        unit_height: { type: integer, in: query }
        legend_width: { type: integer, in: query }
        exclude: { type: integer, in: query, description: "Device ID to exclude" }
        expand_devices: { type: boolean, in: query }
        include_images: { type: boolean, in: query }
      pagination: none

    # =========================================================================
    # DCIM -- Rack Roles, Types & Reservations
    # =========================================================================

    list_rack_roles:
      method: GET
      path: /dcim/rack-roles/
      access: read
      description: "List rack roles (functional classification of racks)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_rack_role:
      method: GET
      path: /dcim/rack-roles/{id}/
      access: read
      description: "Get a specific rack role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_rack_role:
      method: POST
      path: /dcim/rack-roles/
      access: write
      description: "Create a rack role"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        color: { type: string, in: body, description: "6-char hex color" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_rack_role:
      method: PATCH
      path: /dcim/rack-roles/{id}/
      access: write
      description: "Update a rack role"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        color: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_rack_role:
      method: DELETE
      path: /dcim/rack-roles/{id}/
      access: dangerous
      description: "Delete a rack role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_rack_types:
      method: GET
      path: /dcim/rack-types/
      access: read
      description: "List rack types (reusable rack model definitions, NetBox 4.1+)"
      params:
        model: { type: string, in: query }
        slug: { type: string, in: query }
        manufacturer: { type: string, in: query }
        manufacturer_id: { type: integer, in: query }
        form_factor: { type: string, in: query, description: "2-post-frame, 4-post-frame, 4-post-cabinet, wall-frame, wall-cabinet" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_rack_type:
      method: GET
      path: /dcim/rack-types/{id}/
      access: read
      description: "Get a specific rack type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_rack_type:
      method: POST
      path: /dcim/rack-types/
      access: write
      description: "Create a rack type"
      params:
        manufacturer: { type: integer, in: body, required: true }
        model: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        form_factor: { type: string, in: body, description: "2-post-frame, 4-post-frame, 4-post-cabinet, wall-frame, wall-cabinet" }
        width: { type: integer, in: body, description: "Width in inches (10, 19, 21, 23)" }
        u_height: { type: integer, in: body, description: "Default rack height in units" }
        starting_unit: { type: integer, in: body }
        desc_units: { type: boolean, in: body, description: "Numbering descending from top" }
        outer_width: { type: integer, in: body }
        outer_depth: { type: integer, in: body }
        outer_unit: { type: string, in: body, description: "mm or in" }
        weight: { type: number, in: body }
        max_weight: { type: integer, in: body }
        weight_unit: { type: string, in: body, description: "kg, g, lb, oz" }
        mounting_depth: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_rack_type:
      method: PATCH
      path: /dcim/rack-types/{id}/
      access: write
      description: "Update a rack type"
      params:
        id: { type: integer, in: path, required: true }
        manufacturer: { type: integer, in: body }
        model: { type: string, in: body }
        slug: { type: string, in: body }
        form_factor: { type: string, in: body }
        width: { type: integer, in: body }
        u_height: { type: integer, in: body }
        starting_unit: { type: integer, in: body }
        desc_units: { type: boolean, in: body }
        outer_width: { type: integer, in: body }
        outer_depth: { type: integer, in: body }
        outer_unit: { type: string, in: body }
        weight: { type: number, in: body }
        max_weight: { type: integer, in: body }
        weight_unit: { type: string, in: body }
        mounting_depth: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_rack_type:
      method: DELETE
      path: /dcim/rack-types/{id}/
      access: dangerous
      description: "Delete a rack type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_rack_reservations:
      method: GET
      path: /dcim/rack-reservations/
      access: read
      description: "List rack reservations (claimed rack units for future use)"
      params:
        rack: { type: integer, in: query }
        rack_id: { type: integer, in: query }
        site: { type: string, in: query }
        user: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_rack_reservation:
      method: GET
      path: /dcim/rack-reservations/{id}/
      access: read
      description: "Get a specific rack reservation"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_rack_reservation:
      method: POST
      path: /dcim/rack-reservations/
      access: write
      description: "Reserve rack units for future installation"
      params:
        rack: { type: integer, in: body, required: true }
        units: { type: array, in: body, required: true, description: "Array of unit numbers (e.g. [1,2,3,4])" }
        user: { type: integer, in: body, required: true, description: "User ID who owns the reservation" }
        tenant: { type: integer, in: body }
        description: { type: string, in: body, required: true }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_rack_reservation:
      method: PATCH
      path: /dcim/rack-reservations/{id}/
      access: write
      description: "Update a rack reservation"
      params:
        id: { type: integer, in: path, required: true }
        rack: { type: integer, in: body }
        units: { type: array, in: body }
        user: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_rack_reservation:
      method: DELETE
      path: /dcim/rack-reservations/{id}/
      access: dangerous
      description: "Delete a rack reservation"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Devices
    # =========================================================================

    list_manufacturers:
      method: GET
      path: /dcim/manufacturers/
      access: read
      description: "List hardware manufacturers"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_manufacturer:
      method: POST
      path: /dcim/manufacturers/
      access: write
      description: "Create a hardware manufacturer"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_manufacturer:
      method: GET
      path: /dcim/manufacturers/{id}/
      access: read
      description: "Get a specific manufacturer"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_manufacturer:
      method: PATCH
      path: /dcim/manufacturers/{id}/
      access: write
      description: "Update a manufacturer"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_manufacturer:
      method: DELETE
      path: /dcim/manufacturers/{id}/
      access: dangerous
      description: "Delete a manufacturer"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_device_types:
      method: GET
      path: /dcim/device-types/
      access: read
      description: "List device types (hardware models)"
      params:
        manufacturer: { type: string, in: query }
        model: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_device_type:
      method: POST
      path: /dcim/device-types/
      access: write
      description: "Create a device type (hardware model)"
      params:
        manufacturer: { type: integer, in: body, required: true }
        model: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        u_height: { type: number, in: body, description: "Height in rack units (default 1)" }
        is_full_depth: { type: boolean, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_device_type:
      method: GET
      path: /dcim/device-types/{id}/
      access: read
      description: "Get a specific device type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_device_type:
      method: PATCH
      path: /dcim/device-types/{id}/
      access: write
      description: "Update a device type"
      params:
        id: { type: integer, in: path, required: true }
        model: { type: string, in: body }
        u_height: { type: number, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_device_type:
      method: DELETE
      path: /dcim/device-types/{id}/
      access: dangerous
      description: "Delete a device type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_device_roles:
      method: GET
      path: /dcim/device-roles/
      access: read
      description: "List device roles (server, switch, router, firewall, etc.)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_device_role:
      method: POST
      path: /dcim/device-roles/
      access: write
      description: "Create a device role"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        color: { type: string, in: body, description: "6-char hex color (e.g. aa1409)" }
        vm_role: { type: boolean, in: body, description: "Allow assignment to virtual machines" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_device_role:
      method: GET
      path: /dcim/device-roles/{id}/
      access: read
      description: "Get a specific device role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_device_role:
      method: PATCH
      path: /dcim/device-roles/{id}/
      access: write
      description: "Update a device role"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        color: { type: string, in: body }
        vm_role: { type: boolean, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_device_role:
      method: DELETE
      path: /dcim/device-roles/{id}/
      access: dangerous
      description: "Delete a device role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_platforms:
      method: GET
      path: /dcim/platforms/
      access: read
      description: "List platforms (OS/firmware: Cisco IOS, Junos, Linux, etc.)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_platform:
      method: POST
      path: /dcim/platforms/
      access: write
      description: "Create a platform (OS/firmware type)"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        manufacturer: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_platform:
      method: GET
      path: /dcim/platforms/{id}/
      access: read
      description: "Get a specific platform"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_platform:
      method: PATCH
      path: /dcim/platforms/{id}/
      access: write
      description: "Update a platform"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_platform:
      method: DELETE
      path: /dcim/platforms/{id}/
      access: dangerous
      description: "Delete a platform"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_devices:
      method: GET
      path: /dcim/devices/
      access: read
      description: "List all devices (servers, switches, routers, firewalls, etc.)"
      params:
        name: { type: string, in: query }
        site: { type: string, in: query }
        site_id: { type: integer, in: query }
        rack_id: { type: integer, in: query }
        role: { type: string, in: query }
        manufacturer: { type: string, in: query }
        device_type: { type: string, in: query }
        platform: { type: string, in: query }
        status: { type: string, in: query, description: "offline, active, planned, staged, failed, decommissioning" }
        location: { type: string, in: query }
        cluster_id: { type: integer, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }
        ordering: { type: string, in: query }

    get_device:
      method: GET
      path: /dcim/devices/{id}/
      access: read
      description: "Get a specific device with all details"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_device:
      method: POST
      path: /dcim/devices/
      access: write
      description: "Create a new device"
      params:
        name: { type: string, in: body, required: true }
        device_type: { type: integer, in: body, required: true }
        role: { type: integer, in: body, required: true }
        site: { type: integer, in: body, required: true }
        location: { type: integer, in: body, description: "ID of the location (room/floor)" }
        rack: { type: integer, in: body }
        position: { type: number, in: body, description: "Rack unit position" }
        face: { type: string, in: body, description: "front or rear" }
        status: { type: string, in: body }
        platform: { type: integer, in: body }
        serial: { type: string, in: body }
        tenant: { type: integer, in: body }
        cluster: { type: integer, in: body, description: "ID of the virtualization cluster" }
        asset_tag: { type: string, in: body, description: "Unique asset tag" }
        airflow: { type: string, in: body, description: "front-to-rear, rear-to-front, left-to-right, right-to-left, side-to-rear, passive, mixed" }
        virtual_chassis: { type: integer, in: body, description: "ID of the virtual chassis to join as a member" }
        vc_position: { type: integer, in: body, description: "Position within the virtual chassis (0-255, unique per VC)" }
        vc_priority: { type: integer, in: body, description: "Master election priority within the virtual chassis (0-255)" }
        latitude: { type: number, in: body, description: "GPS latitude in decimal degrees" }
        longitude: { type: number, in: body, description: "GPS longitude in decimal degrees" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    update_device:
      method: PATCH
      path: /dcim/devices/{id}/
      access: write
      description: "Update a device -- fields, rack placement, primary IPs, out-of-band (OOB) management IP, virtual-chassis membership, geolocation. IP fields (primary_ip4/primary_ip6/oob_ip) take an ip-address ID that must already be assigned to an interface of this device."
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        status: { type: string, in: body }
        platform: { type: integer, in: body }
        serial: { type: string, in: body }
        rack: { type: integer, in: body }
        position: { type: number, in: body, description: "Rack unit position" }
        face: { type: string, in: body, description: "front or rear" }
        asset_tag: { type: string, in: body, description: "Unique asset tag" }
        airflow: { type: string, in: body, description: "front-to-rear, rear-to-front, left-to-right, right-to-left, side-to-rear, passive, mixed" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
        device_type: { type: integer, in: body, description: "ID of the device type" }
        role: { type: integer, in: body, description: "ID of the device role" }
        site: { type: integer, in: body, description: "ID of the site" }
        location: { type: integer, in: body, description: "ID of the location (room/floor)" }
        cluster: { type: integer, in: body, description: "ID of the virtualization cluster" }
        tenant: { type: integer, in: body, description: "ID of the tenant" }
        primary_ip4: { type: integer, in: body, description: "ID of the primary IPv4 address. Must be assigned to an interface of this device. Nullable: pass null to clear." }
        primary_ip6: { type: integer, in: body, description: "ID of the primary IPv6 address. Must be assigned to an interface of this device. Nullable: pass null to clear." }
        oob_ip: { type: integer, in: body, description: "ID of the out-of-band management IP (BMC/iDRAC/iLO). Must be assigned to an interface of this device, or NAT-linked (nat_inside) to one -- otherwise HTTP 400. Nullable: pass null to clear." }
        virtual_chassis: { type: integer, in: body, description: "ID of the virtual chassis this device is a member of. Nullable: pass null to remove from the VC." }
        vc_position: { type: integer, in: body, description: "Position within the virtual chassis (0-255, unique per VC)" }
        vc_priority: { type: integer, in: body, description: "Master election priority within the virtual chassis (0-255)" }
        latitude: { type: number, in: body, description: "GPS latitude in decimal degrees" }
        longitude: { type: number, in: body, description: "GPS longitude in decimal degrees" }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    delete_device:
      method: DELETE
      path: /dcim/devices/{id}/
      access: dangerous
      description: "Delete a device"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Modules & Module Types
    # =========================================================================

    list_module_types:
      method: GET
      path: /dcim/module-types/
      access: read
      description: "List module types (reusable hardware module definitions, e.g. line cards)"
      params:
        manufacturer: { type: string, in: query }
        manufacturer_id: { type: integer, in: query }
        model: { type: string, in: query }
        part_number: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_module_type:
      method: GET
      path: /dcim/module-types/{id}/
      access: read
      description: "Get a specific module type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_module_type:
      method: POST
      path: /dcim/module-types/
      access: write
      description: "Create a module type"
      params:
        manufacturer: { type: integer, in: body, required: true }
        model: { type: string, in: body, required: true }
        part_number: { type: string, in: body }
        airflow: { type: string, in: body, description: "front-to-rear, rear-to-front, left-to-right, right-to-left, side-to-rear, passive, mixed" }
        weight: { type: number, in: body }
        weight_unit: { type: string, in: body }
        profile: { type: integer, in: body, description: "Module type profile ID" }
        attributes: { type: object, in: body, description: "Profile-specific attributes as key-value object" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_module_type:
      method: PATCH
      path: /dcim/module-types/{id}/
      access: write
      description: "Update a module type"
      params:
        id: { type: integer, in: path, required: true }
        manufacturer: { type: integer, in: body }
        model: { type: string, in: body }
        part_number: { type: string, in: body }
        airflow: { type: string, in: body }
        weight: { type: number, in: body }
        weight_unit: { type: string, in: body }
        profile: { type: integer, in: body }
        attributes: { type: object, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_module_type:
      method: DELETE
      path: /dcim/module-types/{id}/
      access: dangerous
      description: "Delete a module type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_module_type_profiles:
      method: GET
      path: /dcim/module-type-profiles/
      access: read
      description: "List module type profiles (schemas for module-type custom attributes, NetBox 4.3+)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_module_type_profile:
      method: GET
      path: /dcim/module-type-profiles/{id}/
      access: read
      description: "Get a specific module type profile"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_module_type_profile:
      method: POST
      path: /dcim/module-type-profiles/
      access: admin
      description: "Create a module type profile (JSON Schema describing module-type attributes)"
      params:
        name: { type: string, in: body, required: true }
        schema: { type: object, in: body, description: "JSON Schema for the profile's attributes" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_module_type_profile:
      method: PATCH
      path: /dcim/module-type-profiles/{id}/
      access: admin
      description: "Update a module type profile"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        schema: { type: object, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_module_type_profile:
      method: DELETE
      path: /dcim/module-type-profiles/{id}/
      access: dangerous
      description: "Delete a module type profile"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_modules:
      method: GET
      path: /dcim/modules/
      access: read
      description: "List installed modules (instances of module-types mounted in module-bays)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        module_bay: { type: string, in: query }
        module_bay_id: { type: integer, in: query }
        module_type: { type: string, in: query }
        module_type_id: { type: integer, in: query }
        serial: { type: string, in: query }
        status: { type: string, in: query, description: "offline, active, planned, staged, side-loaded, faulty, decommissioning" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_module:
      method: GET
      path: /dcim/modules/{id}/
      access: read
      description: "Get a specific module"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_module:
      method: POST
      path: /dcim/modules/
      access: write
      description: "Install a module into a module bay"
      params:
        device: { type: integer, in: body, required: true }
        module_bay: { type: integer, in: body, required: true }
        module_type: { type: integer, in: body, required: true }
        status: { type: string, in: body, description: "offline, active, planned, staged, side-loaded, faulty, decommissioning" }
        serial: { type: string, in: body }
        asset_tag: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_module:
      method: PATCH
      path: /dcim/modules/{id}/
      access: write
      description: "Update a module"
      params:
        id: { type: integer, in: path, required: true }
        device: { type: integer, in: body }
        module_bay: { type: integer, in: body }
        module_type: { type: integer, in: body }
        status: { type: string, in: body }
        serial: { type: string, in: body }
        asset_tag: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_module:
      method: DELETE
      path: /dcim/modules/{id}/
      access: dangerous
      description: "Delete a module"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_module_bays:
      method: GET
      path: /dcim/module-bays/
      access: read
      description: "List module bays (slots on a device that accept modules)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_module_bay:
      method: GET
      path: /dcim/module-bays/{id}/
      access: read
      description: "Get a specific module bay"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_module_bay:
      method: POST
      path: /dcim/module-bays/
      access: write
      description: "Create a module bay on a device"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        position: { type: string, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_module_bay:
      method: PATCH
      path: /dcim/module-bays/{id}/
      access: write
      description: "Update a module bay"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        position: { type: string, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_module_bay:
      method: DELETE
      path: /dcim/module-bays/{id}/
      access: dangerous
      description: "Delete a module bay"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Device Bays, Virtual Chassis & Inventory
    # =========================================================================

    list_device_bays:
      method: GET
      path: /dcim/device-bays/
      access: read
      description: "List device bays (slots that contain child devices, e.g. blade chassis)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_device_bay:
      method: GET
      path: /dcim/device-bays/{id}/
      access: read
      description: "Get a specific device bay"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_device_bay:
      method: POST
      path: /dcim/device-bays/
      access: write
      description: "Create a device bay"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        installed_device: { type: integer, in: body, description: "Child device ID to install in this bay" }
        label: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_device_bay:
      method: PATCH
      path: /dcim/device-bays/{id}/
      access: write
      description: "Update a device bay"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        installed_device: { type: integer, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_device_bay:
      method: DELETE
      path: /dcim/device-bays/{id}/
      access: dangerous
      description: "Delete a device bay"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_chassis:
      method: GET
      path: /dcim/virtual-chassis/
      access: read
      description: "List virtual chassis (logical grouping of stacked devices that share a single management plane)"
      params:
        name: { type: string, in: query }
        domain: { type: string, in: query }
        master: { type: string, in: query }
        master_id: { type: integer, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_virtual_chassis:
      method: GET
      path: /dcim/virtual-chassis/{id}/
      access: read
      description: "Get a specific virtual chassis"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_virtual_chassis:
      method: POST
      path: /dcim/virtual-chassis/
      access: write
      description: "Create a virtual chassis. Assign devices via PATCH /dcim/devices/ to set virtual_chassis and vc_position fields."
      params:
        name: { type: string, in: body, required: true }
        domain: { type: string, in: body }
        master: { type: integer, in: body, description: "ID of the device that is the chassis master" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_virtual_chassis:
      method: PATCH
      path: /dcim/virtual-chassis/{id}/
      access: write
      description: "Update a virtual chassis"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        domain: { type: string, in: body }
        master: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_virtual_chassis:
      method: DELETE
      path: /dcim/virtual-chassis/{id}/
      access: dangerous
      description: "Delete a virtual chassis"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_device_contexts:
      method: GET
      path: /dcim/virtual-device-contexts/
      access: read
      description: "List virtual device contexts (VDCs -- multiple logical contexts on one physical device, e.g. Cisco Nexus VDCs)"
      params:
        name: { type: string, in: query }
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        status: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_virtual_device_context:
      method: GET
      path: /dcim/virtual-device-contexts/{id}/
      access: read
      description: "Get a specific VDC"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_virtual_device_context:
      method: POST
      path: /dcim/virtual-device-contexts/
      access: write
      description: "Create a virtual device context"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        identifier: { type: integer, in: body, description: "Numeric VDC identifier" }
        status: { type: string, in: body, description: "active, planned, offline" }
        tenant: { type: integer, in: body }
        primary_ip4: { type: integer, in: body }
        primary_ip6: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_virtual_device_context:
      method: PATCH
      path: /dcim/virtual-device-contexts/{id}/
      access: write
      description: "Update a virtual device context"
      params:
        id: { type: integer, in: path, required: true }
        device: { type: integer, in: body }
        name: { type: string, in: body }
        identifier: { type: integer, in: body }
        status: { type: string, in: body }
        tenant: { type: integer, in: body }
        primary_ip4: { type: integer, in: body }
        primary_ip6: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_virtual_device_context:
      method: DELETE
      path: /dcim/virtual-device-contexts/{id}/
      access: dangerous
      description: "Delete a virtual device context"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_inventory_items:
      method: GET
      path: /dcim/inventory-items/
      access: read
      description: "List inventory items (line cards, fans, PSUs not modeled as full modules)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        manufacturer: { type: string, in: query }
        serial: { type: string, in: query }
        asset_tag: { type: string, in: query }
        discovered: { type: boolean, in: query }
        parent_id: { type: integer, in: query }
        role: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_inventory_item:
      method: GET
      path: /dcim/inventory-items/{id}/
      access: read
      description: "Get a specific inventory item"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_inventory_item:
      method: POST
      path: /dcim/inventory-items/
      access: write
      description: "Create an inventory item on a device"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        parent: { type: integer, in: body, description: "Parent inventory item for hierarchical items" }
        role: { type: integer, in: body, description: "Inventory item role ID" }
        manufacturer: { type: integer, in: body }
        part_id: { type: string, in: body }
        serial: { type: string, in: body }
        asset_tag: { type: string, in: body }
        discovered: { type: boolean, in: body }
        component_type: { type: string, in: body, description: "ContentType, e.g. dcim.interface" }
        component_id: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_inventory_item:
      method: PATCH
      path: /dcim/inventory-items/{id}/
      access: write
      description: "Update an inventory item"
      params:
        id: { type: integer, in: path, required: true }
        device: { type: integer, in: body }
        name: { type: string, in: body }
        parent: { type: integer, in: body }
        role: { type: integer, in: body }
        manufacturer: { type: integer, in: body }
        part_id: { type: string, in: body }
        serial: { type: string, in: body }
        asset_tag: { type: string, in: body }
        discovered: { type: boolean, in: body }
        component_type: { type: string, in: body }
        component_id: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_inventory_item:
      method: DELETE
      path: /dcim/inventory-items/{id}/
      access: dangerous
      description: "Delete an inventory item"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_inventory_item_roles:
      method: GET
      path: /dcim/inventory-item-roles/
      access: read
      description: "List inventory item roles (functional classification, e.g. CPU, PSU, Fan)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_inventory_item_role:
      method: GET
      path: /dcim/inventory-item-roles/{id}/
      access: read
      description: "Get a specific inventory item role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_inventory_item_role:
      method: POST
      path: /dcim/inventory-item-roles/
      access: write
      description: "Create an inventory item role"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        color: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_inventory_item_role:
      method: PATCH
      path: /dcim/inventory-item-roles/{id}/
      access: write
      description: "Update an inventory item role"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        color: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_inventory_item_role:
      method: DELETE
      path: /dcim/inventory-item-roles/{id}/
      access: dangerous
      description: "Delete an inventory item role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Interfaces & Cables
    # =========================================================================

    list_interfaces:
      method: GET
      path: /dcim/interfaces/
      access: read
      description: "List device interfaces (physical and logical)"
      params:
        device: { type: string, in: query, description: "Device name" }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        type: { type: string, in: query }
        enabled: { type: boolean, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_interface:
      method: GET
      path: /dcim/interfaces/{id}/
      access: read
      description: "Get a specific interface"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_interface:
      method: POST
      path: /dcim/interfaces/
      access: write
      description: "Create a device interface"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true, description: "e.g. 1000base-t, 10gbase-x-sfpp, 25gbase-x-sfp28, virtual, lag" }
        enabled: { type: boolean, in: body }
        mtu: { type: integer, in: body }
        primary_mac_address: { type: integer, in: body, description: "Primary MAC address object ID. NetBox 4.x stores MACs as separate objects: create_mac_address first (assigned to this interface), then set its ID here. The interface's mac_address field itself is read-only." }
        mgmt_only: { type: boolean, in: body, description: "Management-only interface" }
        label: { type: string, in: body, description: "Physical label" }
        speed: { type: integer, in: body, description: "Speed in Kbps" }
        duplex: { type: string, in: body, description: "half, full, auto" }
        parent: { type: integer, in: body, description: "Parent interface ID" }
        bridge: { type: integer, in: body, description: "Bridge interface ID" }
        lag: { type: integer, in: body, description: "LAG interface ID" }
        vrf: { type: integer, in: body, description: "VRF assignment" }
        description: { type: string, in: body }
        mode: { type: string, in: body, description: "access, tagged, tagged-all" }
        untagged_vlan: { type: integer, in: body }
        tagged_vlans: { type: array, in: body }
        wireless_lans: { type: array, in: body, description: "Array of wireless_lan IDs (M2M). Empty array detaches all." }
        tags: { type: array, in: body }
      pagination: none

    update_interface:
      method: PATCH
      path: /dcim/interfaces/{id}/
      access: write
      description: >
        Update a device interface. Nullable foreign keys and choice fields accept
        an explicit JSON null to clear -- omitting the field leaves it unchanged.
        Nullable params: untagged_vlan, lag, parent, bridge, vrf, primary_mac_address,
        mode, duplex. For M2M wireless_lans / tagged_vlans / tags pass [] to detach all.
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body, description: "e.g. 1000base-t, 10gbase-x-sfpp, 25gbase-x-sfp28, virtual, lag" }
        enabled: { type: boolean, in: body }
        mtu: { type: integer, in: body }
        primary_mac_address: { type: integer, in: body, description: "Primary MAC address object ID. NetBox 4.x stores MACs as separate objects: create_mac_address first (assigned to this interface), then set its ID here. The interface's mac_address field itself is read-only. Nullable: pass null to clear." }
        mgmt_only: { type: boolean, in: body, description: "Management-only interface" }
        label: { type: string, in: body, description: "Physical label" }
        speed: { type: integer, in: body, description: "Speed in Kbps" }
        duplex: { type: string, in: body, description: "half, full, auto. Nullable: pass null to clear." }
        parent: { type: integer, in: body, description: "Parent interface ID. Nullable: pass null to clear." }
        bridge: { type: integer, in: body, description: "Bridge interface ID. Nullable: pass null to clear." }
        lag: { type: integer, in: body, description: "LAG interface ID. Nullable: pass null to clear." }
        vrf: { type: integer, in: body, description: "VRF assignment. Nullable: pass null to clear." }
        description: { type: string, in: body }
        mode: { type: string, in: body, description: "access, tagged, tagged-all. Nullable: pass null to clear (unsets trunk mode)." }
        untagged_vlan: { type: integer, in: body, description: "Untagged native VLAN ID. Nullable: pass null to clear." }
        tagged_vlans: { type: array, in: body, description: "Array of VLAN IDs allowed when mode is tagged. Pass [] to detach all." }
        wireless_lans: { type: array, in: body, description: "Array of wireless_lan IDs (M2M). Pass [] to detach all." }
        tags: { type: array, in: body }
      pagination: none

    delete_interface:
      method: DELETE
      path: /dcim/interfaces/{id}/
      access: write
      description: "Delete a device interface"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_cables:
      method: GET
      path: /dcim/cables/
      access: read
      description: "List all cables connecting device components"
      params:
        site: { type: string, in: query }
        device: { type: string, in: query }
        type: { type: string, in: query }
        status: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_cable:
      method: GET
      path: /dcim/cables/{id}/
      access: read
      description: "Get a specific cable"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_cable:
      method: POST
      path: /dcim/cables/
      access: write
      description: "Create a cable connection between device components"
      params:
        a_terminations: { type: array, in: body, required: true, description: "Array of {object_type, object_id}" }
        b_terminations: { type: array, in: body, required: true, description: "Array of {object_type, object_id}" }
        type: { type: string, in: body, description: "cat5e, cat6, cat6a, fiber-om3, fiber-sm, power, etc." }
        status: { type: string, in: body, description: "connected, planned, decommissioning" }
        label: { type: string, in: body }
        length: { type: number, in: body }
        length_unit: { type: string, in: body, description: "m, cm, ft, in" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_cable:
      method: PATCH
      path: /dcim/cables/{id}/
      access: write
      description: "Update a cable"
      params:
        id: { type: integer, in: path, required: true }
        type: { type: string, in: body }
        status: { type: string, in: body }
        label: { type: string, in: body }
        length: { type: number, in: body }
        length_unit: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_cable:
      method: DELETE
      path: /dcim/cables/{id}/
      access: dangerous
      description: "Delete a cable"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_console_ports:
      method: GET
      path: /dcim/console-ports/
      access: read
      description: "List device console ports"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_console_port:
      method: POST
      path: /dcim/console-ports/
      access: write
      description: "Create a console port on a device"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, description: "de-9, db-25, rj-45, usb-a, usb-c, other" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_power_ports:
      method: GET
      path: /dcim/power-ports/
      access: read
      description: "List device power ports"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_power_port:
      method: POST
      path: /dcim/power-ports/
      access: write
      description: "Create a power port on a device"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, description: "iec-60320-c14, iec-60320-c16, nema-5-15p, etc." }
        maximum_draw: { type: integer, in: body, description: "Maximum power draw in watts" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_mac_addresses:
      method: GET
      path: /dcim/mac-addresses/
      access: read
      description: "List MAC addresses"
      params:
        device: { type: string, in: query }
        interface: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_mac_address:
      method: POST
      path: /dcim/mac-addresses/
      access: write
      description: "Create a MAC address entry"
      params:
        mac_address: { type: string, in: body, required: true, description: "MAC address (e.g. 00:1A:2B:3C:4D:5E)" }
        assigned_object_type: { type: string, in: body, description: "dcim.interface or virtualization.vminterface" }
        assigned_object_id: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_mac_address:
      method: GET
      path: /dcim/mac-addresses/{id}/
      access: read
      description: "Get a specific MAC address entry"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_mac_address:
      method: PATCH
      path: /dcim/mac-addresses/{id}/
      access: write
      description: "Update a MAC address entry (reassign to different interface, change description)"
      params:
        id: { type: integer, in: path, required: true }
        mac_address: { type: string, in: body }
        assigned_object_type: { type: string, in: body, description: "dcim.interface or virtualization.vminterface" }
        assigned_object_id: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_mac_address:
      method: DELETE
      path: /dcim/mac-addresses/{id}/
      access: dangerous
      description: "Delete a MAC address entry"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Front/Rear/Console-Server Ports & Power Outlets
    # =========================================================================

    get_console_port:
      method: GET
      path: /dcim/console-ports/{id}/
      access: read
      description: "Get a specific console port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_console_port:
      method: PATCH
      path: /dcim/console-ports/{id}/
      access: write
      description: "Update a console port"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        speed: { type: integer, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_console_port:
      method: DELETE
      path: /dcim/console-ports/{id}/
      access: dangerous
      description: "Delete a console port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    trace_console_port:
      method: GET
      path: /dcim/console-ports/{id}/trace/
      access: read
      description: "Trace the cable path from this console port to its far end (returns a list of cable segments)"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_console_server_ports:
      method: GET
      path: /dcim/console-server-ports/
      access: read
      description: "List console server ports (the server-side of console connections)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        type: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_console_server_port:
      method: GET
      path: /dcim/console-server-ports/{id}/
      access: read
      description: "Get a specific console server port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_console_server_port:
      method: POST
      path: /dcim/console-server-ports/
      access: write
      description: "Create a console server port"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, description: "de-9, db-25, rj-45, usb-a, usb-c, other" }
        speed: { type: integer, in: body, description: "Baud rate (e.g. 9600, 115200)" }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_console_server_port:
      method: PATCH
      path: /dcim/console-server-ports/{id}/
      access: write
      description: "Update a console server port"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        speed: { type: integer, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_console_server_port:
      method: DELETE
      path: /dcim/console-server-ports/{id}/
      access: dangerous
      description: "Delete a console server port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_power_port:
      method: GET
      path: /dcim/power-ports/{id}/
      access: read
      description: "Get a specific power port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_power_port:
      method: PATCH
      path: /dcim/power-ports/{id}/
      access: write
      description: "Update a power port"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        maximum_draw: { type: integer, in: body }
        allocated_draw: { type: integer, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_power_port:
      method: DELETE
      path: /dcim/power-ports/{id}/
      access: dangerous
      description: "Delete a power port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_power_outlets:
      method: GET
      path: /dcim/power-outlets/
      access: read
      description: "List power outlets (sockets on a PDU or device that supply power to other devices)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        type: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_power_outlet:
      method: GET
      path: /dcim/power-outlets/{id}/
      access: read
      description: "Get a specific power outlet"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_power_outlet:
      method: POST
      path: /dcim/power-outlets/
      access: write
      description: "Create a power outlet (typically on a PDU)"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, description: "iec-60320-c5, iec-60320-c7, iec-60320-c13, iec-60320-c15, iec-60320-c19, iec-60320-c21, nema-1-15r, nema-5-15r, etc." }
        power_port: { type: integer, in: body, description: "Upstream power port that feeds this outlet" }
        feed_leg: { type: string, in: body, description: "A, B, or C (for multi-phase power)" }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_power_outlet:
      method: PATCH
      path: /dcim/power-outlets/{id}/
      access: write
      description: "Update a power outlet"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        power_port: { type: integer, in: body }
        feed_leg: { type: string, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_power_outlet:
      method: DELETE
      path: /dcim/power-outlets/{id}/
      access: dangerous
      description: "Delete a power outlet"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_front_ports:
      method: GET
      path: /dcim/front-ports/
      access: read
      description: "List front ports (patch panel front-side ports, paired with rear ports)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        type: { type: string, in: query }
        rear_port: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_front_port:
      method: GET
      path: /dcim/front-ports/{id}/
      access: read
      description: "Get a specific front port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_front_port:
      method: POST
      path: /dcim/front-ports/
      access: write
      description: "Create a front port on a patch panel (must reference a rear port)"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true, description: "8p8c, 8p6c, 8p4c, 8p2c, 6p6c, 6p4c, 6p2c, 4p4c, 4p2c, gg45, tera-4p, tera-2p, tera-1p, 110-punch, bnc, f, n, mrj21, fc, lc, lc-pc, lc-upc, lc-apc, lsh, lsh-pc, lsh-upc, lsh-apc, lx5, lx5-pc, lx5-upc, lx5-apc, mpo, mtrj, sc, sc-pc, sc-upc, sc-apc, st, cs, sn, sma-905, sma-906, urm-p2, urm-p4, urm-p8, splice, other" }
        color: { type: string, in: body }
        rear_port: { type: integer, in: body, required: true }
        rear_port_position: { type: integer, in: body, default: 1 }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_front_port:
      method: PATCH
      path: /dcim/front-ports/{id}/
      access: write
      description: "Update a front port"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        color: { type: string, in: body }
        rear_port: { type: integer, in: body }
        rear_port_position: { type: integer, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_front_port:
      method: DELETE
      path: /dcim/front-ports/{id}/
      access: dangerous
      description: "Delete a front port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    paths_front_port:
      method: GET
      path: /dcim/front-ports/{id}/paths/
      access: read
      description: "List all cable paths that pass through this front port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_rear_ports:
      method: GET
      path: /dcim/rear-ports/
      access: read
      description: "List rear ports (patch panel rear-side ports, cabled to trunk lines)"
      params:
        device: { type: string, in: query }
        device_id: { type: integer, in: query }
        name: { type: string, in: query }
        type: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_rear_port:
      method: GET
      path: /dcim/rear-ports/{id}/
      access: read
      description: "Get a specific rear port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_rear_port:
      method: POST
      path: /dcim/rear-ports/
      access: write
      description: "Create a rear port on a patch panel"
      params:
        device: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true, description: "Connector type (see front-port types)" }
        color: { type: string, in: body }
        positions: { type: integer, in: body, default: 1, description: "Number of front-port positions this rear port supports" }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_rear_port:
      method: PATCH
      path: /dcim/rear-ports/{id}/
      access: write
      description: "Update a rear port"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        color: { type: string, in: body }
        positions: { type: integer, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        mark_connected: { type: boolean, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_rear_port:
      method: DELETE
      path: /dcim/rear-ports/{id}/
      access: dangerous
      description: "Delete a rear port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    paths_rear_port:
      method: GET
      path: /dcim/rear-ports/{id}/paths/
      access: read
      description: "List all cable paths that pass through this rear port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    trace_interface:
      method: GET
      path: /dcim/interfaces/{id}/trace/
      access: read
      description: "Trace the cable path from this interface to its far end"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    trace_power_port:
      method: GET
      path: /dcim/power-ports/{id}/trace/
      access: read
      description: "Trace the cable path from this power port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    trace_power_outlet:
      method: GET
      path: /dcim/power-outlets/{id}/trace/
      access: read
      description: "Trace the cable path from this power outlet"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    trace_console_server_port:
      method: GET
      path: /dcim/console-server-ports/{id}/trace/
      access: read
      description: "Trace the cable path from this console server port"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_connected_device:
      method: GET
      path: /dcim/connected-device/
      access: read
      description: >
        Lookup the device connected to a given peer device/interface.
        Returns the device at the far end of the cable, or 404 if not connected.
      params:
        peer_device: { type: string, in: query, required: true }
        peer_interface: { type: string, in: query, required: true }
      pagination: none

    list_cable_terminations:
      method: GET
      path: /dcim/cable-terminations/
      access: read
      description: "List cable terminations (endpoints of cables -- the join between a cable and a port)"
      params:
        cable: { type: integer, in: query }
        cable_id: { type: integer, in: query }
        cable_end: { type: string, in: query, description: "A or B" }
        termination_type: { type: string, in: query }
        termination_id: { type: integer, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_cable_termination:
      method: GET
      path: /dcim/cable-terminations/{id}/
      access: read
      description: "Get a specific cable termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Power Panels & Feeds
    # =========================================================================

    list_power_panels:
      method: GET
      path: /dcim/power-panels/
      access: read
      description: "List power panels (the upstream source of power feeds at a site)"
      params:
        site: { type: string, in: query }
        site_id: { type: integer, in: query }
        location: { type: string, in: query }
        location_id: { type: integer, in: query }
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_power_panel:
      method: GET
      path: /dcim/power-panels/{id}/
      access: read
      description: "Get a specific power panel"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_power_panel:
      method: POST
      path: /dcim/power-panels/
      access: write
      description: "Create a power panel"
      params:
        site: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        location: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_power_panel:
      method: PATCH
      path: /dcim/power-panels/{id}/
      access: write
      description: "Update a power panel"
      params:
        id: { type: integer, in: path, required: true }
        site: { type: integer, in: body }
        name: { type: string, in: body }
        location: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_power_panel:
      method: DELETE
      path: /dcim/power-panels/{id}/
      access: dangerous
      description: "Delete a power panel"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_power_feeds:
      method: GET
      path: /dcim/power-feeds/
      access: read
      description: "List power feeds (the circuit from a power panel that supplies a rack)"
      params:
        power_panel: { type: integer, in: query }
        power_panel_id: { type: integer, in: query }
        rack: { type: integer, in: query }
        rack_id: { type: integer, in: query }
        site: { type: string, in: query }
        name: { type: string, in: query }
        status: { type: string, in: query, description: "offline, active, planned, failed" }
        type: { type: string, in: query, description: "primary, redundant" }
        supply: { type: string, in: query, description: "ac, dc" }
        phase: { type: string, in: query, description: "single-phase, three-phase" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_power_feed:
      method: GET
      path: /dcim/power-feeds/{id}/
      access: read
      description: "Get a specific power feed"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_power_feed:
      method: POST
      path: /dcim/power-feeds/
      access: write
      description: "Create a power feed (circuit from a power panel to a rack)"
      params:
        power_panel: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        rack: { type: integer, in: body }
        status: { type: string, in: body, description: "offline, active, planned, failed" }
        type: { type: string, in: body, description: "primary, redundant" }
        supply: { type: string, in: body, description: "ac, dc" }
        phase: { type: string, in: body, description: "single-phase, three-phase" }
        voltage: { type: integer, in: body, description: "Volts (negative for DC -- e.g. -48)" }
        amperage: { type: integer, in: body }
        max_utilization: { type: integer, in: body, description: "Maximum utilization percent (1-100)" }
        mark_connected: { type: boolean, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tenant: { type: integer, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_power_feed:
      method: PATCH
      path: /dcim/power-feeds/{id}/
      access: write
      description: "Update a power feed"
      params:
        id: { type: integer, in: path, required: true }
        power_panel: { type: integer, in: body }
        rack: { type: integer, in: body }
        name: { type: string, in: body }
        status: { type: string, in: body }
        type: { type: string, in: body }
        supply: { type: string, in: body }
        phase: { type: string, in: body }
        voltage: { type: integer, in: body }
        amperage: { type: integer, in: body }
        max_utilization: { type: integer, in: body }
        mark_connected: { type: boolean, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tenant: { type: integer, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_power_feed:
      method: DELETE
      path: /dcim/power-feeds/{id}/
      access: dangerous
      description: "Delete a power feed"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    trace_power_feed:
      method: GET
      path: /dcim/power-feeds/{id}/trace/
      access: read
      description: "Trace the cable path from this power feed"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # DCIM -- Component Templates
    # =========================================================================
    # Templates define the components that are auto-created when a device-type
    # or module-type is instantiated. Each template type mirrors its concrete
    # component (interface-templates -> interfaces, etc.).
    # All templates share the pattern: scoped to device_type OR module_type,
    # with name/label/type/description fields. Use list + create only -- updates
    # are uncommon (typical workflow is delete + recreate).

    list_interface_templates:
      method: GET
      path: /dcim/interface-templates/
      access: read
      description: "List interface templates on device-types and module-types"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        type: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_interface_template:
      method: POST
      path: /dcim/interface-templates/
      access: write
      description: "Create an interface template. Must specify device_type OR module_type."
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true, description: "e.g. 1000base-t, 10gbase-x-sfpp, 25gbase-x-sfp28, 100gbase-x-qsfp28" }
        enabled: { type: boolean, in: body, default: true }
        mgmt_only: { type: boolean, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        poe_mode: { type: string, in: body, description: "pd or pse" }
        poe_type: { type: string, in: body }
        rf_role: { type: string, in: body }
        bridge: { type: integer, in: body }
      pagination: none

    get_interface_template:
      method: GET
      path: /dcim/interface-templates/{id}/
      access: read
      description: "Get a specific interface template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_interface_template:
      method: PATCH
      path: /dcim/interface-templates/{id}/
      access: write
      description: "Update an interface template"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        enabled: { type: boolean, in: body }
        mgmt_only: { type: boolean, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
        poe_mode: { type: string, in: body }
        poe_type: { type: string, in: body }
      pagination: none

    delete_interface_template:
      method: DELETE
      path: /dcim/interface-templates/{id}/
      access: dangerous
      description: "Delete an interface template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_console_port_templates:
      method: GET
      path: /dcim/console-port-templates/
      access: read
      description: "List console port templates"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_console_port_template:
      method: POST
      path: /dcim/console-port-templates/
      access: write
      description: "Create a console port template"
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_console_port_template:
      method: DELETE
      path: /dcim/console-port-templates/{id}/
      access: dangerous
      description: "Delete a console port template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_console_server_port_templates:
      method: GET
      path: /dcim/console-server-port-templates/
      access: read
      description: "List console server port templates"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_console_server_port_template:
      method: POST
      path: /dcim/console-server-port-templates/
      access: write
      description: "Create a console server port template"
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_console_server_port_template:
      method: DELETE
      path: /dcim/console-server-port-templates/{id}/
      access: dangerous
      description: "Delete a console server port template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_power_port_templates:
      method: GET
      path: /dcim/power-port-templates/
      access: read
      description: "List power port templates"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_power_port_template:
      method: POST
      path: /dcim/power-port-templates/
      access: write
      description: "Create a power port template"
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body }
        maximum_draw: { type: integer, in: body }
        allocated_draw: { type: integer, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_power_port_template:
      method: DELETE
      path: /dcim/power-port-templates/{id}/
      access: dangerous
      description: "Delete a power port template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_power_outlet_templates:
      method: GET
      path: /dcim/power-outlet-templates/
      access: read
      description: "List power outlet templates"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_power_outlet_template:
      method: POST
      path: /dcim/power-outlet-templates/
      access: write
      description: "Create a power outlet template"
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body }
        power_port: { type: integer, in: body, description: "Power port template ID (upstream)" }
        feed_leg: { type: string, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_power_outlet_template:
      method: DELETE
      path: /dcim/power-outlet-templates/{id}/
      access: dangerous
      description: "Delete a power outlet template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_front_port_templates:
      method: GET
      path: /dcim/front-port-templates/
      access: read
      description: "List front port templates"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_front_port_template:
      method: POST
      path: /dcim/front-port-templates/
      access: write
      description: "Create a front port template (must reference a rear-port-template)"
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true }
        color: { type: string, in: body }
        rear_port: { type: integer, in: body, required: true, description: "Rear port template ID" }
        rear_port_position: { type: integer, in: body, default: 1 }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_front_port_template:
      method: DELETE
      path: /dcim/front-port-templates/{id}/
      access: dangerous
      description: "Delete a front port template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_rear_port_templates:
      method: GET
      path: /dcim/rear-port-templates/
      access: read
      description: "List rear port templates"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_rear_port_template:
      method: POST
      path: /dcim/rear-port-templates/
      access: write
      description: "Create a rear port template"
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body }
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true }
        color: { type: string, in: body }
        positions: { type: integer, in: body, default: 1 }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_rear_port_template:
      method: DELETE
      path: /dcim/rear-port-templates/{id}/
      access: dangerous
      description: "Delete a rear port template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_module_bay_templates:
      method: GET
      path: /dcim/module-bay-templates/
      access: read
      description: "List module bay templates"
      params:
        devicetype_id: { type: integer, in: query }
        moduletype_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_module_bay_template:
      method: POST
      path: /dcim/module-bay-templates/
      access: write
      description: "Create a module bay template"
      params:
        device_type: { type: integer, in: body }
        module_type: { type: integer, in: body, description: "Parent module type for nested module bays" }
        name: { type: string, in: body, required: true }
        position: { type: string, in: body }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_module_bay_template:
      method: DELETE
      path: /dcim/module-bay-templates/{id}/
      access: dangerous
      description: "Delete a module bay template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_device_bay_templates:
      method: GET
      path: /dcim/device-bay-templates/
      access: read
      description: "List device bay templates"
      params:
        devicetype_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_device_bay_template:
      method: POST
      path: /dcim/device-bay-templates/
      access: write
      description: "Create a device bay template"
      params:
        device_type: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        label: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_device_bay_template:
      method: DELETE
      path: /dcim/device-bay-templates/{id}/
      access: dangerous
      description: "Delete a device bay template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_inventory_item_templates:
      method: GET
      path: /dcim/inventory-item-templates/
      access: read
      description: "List inventory item templates"
      params:
        devicetype_id: { type: integer, in: query }
        name: { type: string, in: query }
        role: { type: string, in: query }
        manufacturer: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_inventory_item_template:
      method: POST
      path: /dcim/inventory-item-templates/
      access: write
      description: "Create an inventory item template"
      params:
        device_type: { type: integer, in: body, required: true }
        parent: { type: integer, in: body, description: "Parent inventory item template" }
        name: { type: string, in: body, required: true }
        label: { type: string, in: body }
        role: { type: integer, in: body }
        manufacturer: { type: integer, in: body }
        part_id: { type: string, in: body }
        description: { type: string, in: body }
        component_type: { type: string, in: body }
        component_id: { type: integer, in: body }
      pagination: none

    delete_inventory_item_template:
      method: DELETE
      path: /dcim/inventory-item-templates/{id}/
      access: dangerous
      description: "Delete an inventory item template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # IPAM -- Prefixes & IP Addresses
    # =========================================================================

    list_prefixes:
      method: GET
      path: /ipam/prefixes/
      access: read
      description: "List IP prefixes (subnets). Results span ALL VRFs: overlapping private ranges (e.g. a customer VRF reusing an internal RFC1918 net) return look-alike rows -- check the vrf field and scope with vrf_id when a range is ambiguous."
      params:
        prefix: { type: string, in: query, description: "Exact CIDR match" }
        within: { type: string, in: query, description: "CIDR supernet (e.g. 10.0.0.0/8)" }
        contains: { type: string, in: query, description: "IP or prefix contained" }
        site: { type: string, in: query }
        vrf: { type: string, in: query, description: "Filter by VRF route distinguisher (RD). Rejects VRF names; useless for VRFs without an RD -- prefer vrf_id." }
        vrf_id: { type: integer, in: query, description: "Filter by VRF ID -- the reliable way to scope to one VRF" }
        vlan_id: { type: integer, in: query }
        status: { type: string, in: query, description: "container, active, reserved, deprecated" }
        role: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_prefix:
      method: GET
      path: /ipam/prefixes/{id}/
      access: read
      description: "Get a specific prefix"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_prefix:
      method: POST
      path: /ipam/prefixes/
      access: write
      description: "Create an IP prefix"
      params:
        prefix: { type: string, in: body, required: true, description: "CIDR notation (e.g. 10.0.1.0/24)" }
        site: { type: integer, in: body }
        vrf: { type: integer, in: body }
        vlan: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_prefix:
      method: PATCH
      path: /ipam/prefixes/{id}/
      access: write
      description: "Update a prefix"
      params:
        id: { type: integer, in: path, required: true }
        prefix: { type: string, in: body, description: "CIDR notation (e.g. 10.0.1.0/24)" }
        site: { type: integer, in: body }
        vrf: { type: integer, in: body }
        vlan: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_prefix:
      method: DELETE
      path: /ipam/prefixes/{id}/
      access: dangerous
      description: "Delete a prefix"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_available_ips:
      method: GET
      path: /ipam/prefixes/{id}/available-ips/
      access: read
      description: "List available (unallocated) IPs within a prefix"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_ip_addresses:
      method: GET
      path: /ipam/ip-addresses/
      access: read
      description: "List all IP addresses. Results span ALL VRFs: the same private address can exist once globally and again inside a customer VRF -- check the vrf field on each row and scope with vrf_id when an address is ambiguous."
      params:
        address: { type: string, in: query, description: "Exact IP (e.g. 10.0.0.1/24)" }
        parent: { type: string, in: query, description: "Parent prefix CIDR" }
        device: { type: string, in: query }
        virtual_machine: { type: string, in: query }
        interface: { type: string, in: query }
        vrf: { type: string, in: query, description: "Filter by VRF route distinguisher (RD). Rejects VRF names; useless for VRFs without an RD -- prefer vrf_id." }
        vrf_id: { type: integer, in: query, description: "Filter by VRF ID -- the reliable way to scope to one VRF" }
        status: { type: string, in: query, description: "active, reserved, deprecated, dhcp, slaac" }
        role: { type: string, in: query }
        tenant: { type: string, in: query }
        assigned: { type: boolean, in: query, description: "Filter by assigned (true) or unassigned (false)" }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_ip_address:
      method: GET
      path: /ipam/ip-addresses/{id}/
      access: read
      description: "Get a specific IP address"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_ip_address:
      method: POST
      path: /ipam/ip-addresses/
      access: write
      description: "Create an IP address"
      params:
        address: { type: string, in: body, required: true, description: "CIDR (e.g. 10.0.0.1/24)" }
        vrf: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: string, in: body }
        tenant: { type: integer, in: body }
        assigned_object_type: { type: string, in: body, description: "dcim.interface or virtualization.vminterface" }
        assigned_object_id: { type: integer, in: body }
        nat_inside: { type: integer, in: body, description: "ID of the inside (private) IP this address is the 1:1 NAT outside for. Set on the OUTSIDE address; nat_outside is the read-only reverse view." }
        dns_name: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_ip_address:
      method: PATCH
      path: /ipam/ip-addresses/{id}/
      access: write
      description: "Update an IP address"
      params:
        id: { type: integer, in: path, required: true }
        address: { type: string, in: body, description: "CIDR (e.g. 10.0.0.1/24)" }
        vrf: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: string, in: body }
        tenant: { type: integer, in: body }
        dns_name: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        assigned_object_type: { type: string, in: body }
        assigned_object_id: { type: integer, in: body }
        nat_inside: { type: integer, in: body, description: "ID of the inside (private) IP this address is the 1:1 NAT outside for. Set on the OUTSIDE address; nat_outside is the read-only reverse view. Nullable: pass null to clear." }
        tags: { type: array, in: body }
      pagination: none

    delete_ip_address:
      method: DELETE
      path: /ipam/ip-addresses/{id}/
      access: dangerous
      description: "Delete an IP address"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_ip_ranges:
      method: GET
      path: /ipam/ip-ranges/
      access: read
      description: "List IP ranges (continuous address ranges, e.g. DHCP pools)"
      params:
        vrf: { type: string, in: query }
        status: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_ip_range:
      method: POST
      path: /ipam/ip-ranges/
      access: write
      description: "Create an IP range"
      params:
        start_address: { type: string, in: body, required: true, description: "Start IP (CIDR, e.g. 10.0.0.100/24)" }
        end_address: { type: string, in: body, required: true, description: "End IP (CIDR, e.g. 10.0.0.200/24)" }
        vrf: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    # =========================================================================
    # IPAM -- VLANs & VRFs
    # =========================================================================

    list_vlans:
      method: GET
      path: /ipam/vlans/
      access: read
      description: "List all VLANs"
      params:
        vid: { type: integer, in: query, description: "VLAN ID (1-4094)" }
        name: { type: string, in: query }
        site: { type: string, in: query }
        group: { type: string, in: query }
        status: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_vlan:
      method: GET
      path: /ipam/vlans/{id}/
      access: read
      description: "Get a specific VLAN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_vlan:
      method: POST
      path: /ipam/vlans/
      access: write
      description: "Create a VLAN"
      params:
        vid: { type: integer, in: body, required: true, description: "VLAN ID (1-4094)" }
        name: { type: string, in: body, required: true }
        site: { type: integer, in: body }
        group: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_vlan:
      method: PATCH
      path: /ipam/vlans/{id}/
      access: write
      description: "Update a VLAN"
      params:
        id: { type: integer, in: path, required: true }
        vid: { type: integer, in: body, description: "VLAN ID (1-4094)" }
        name: { type: string, in: body }
        site: { type: integer, in: body }
        group: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_vlan:
      method: DELETE
      path: /ipam/vlans/{id}/
      access: dangerous
      description: "Delete a VLAN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_vlan_groups:
      method: GET
      path: /ipam/vlan-groups/
      access: read
      description: "List VLAN groups"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_vlan_group:
      method: POST
      path: /ipam/vlan-groups/
      access: write
      description: "Create a VLAN group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        min_vid: { type: integer, in: body, description: "Minimum VLAN ID (default 1)" }
        max_vid: { type: integer, in: body, description: "Maximum VLAN ID (default 4094)" }
        scope_type: { type: string, in: body, description: "dcim.site, dcim.location, dcim.rack, etc." }
        scope_id: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_vlan_group:
      method: GET
      path: /ipam/vlan-groups/{id}/
      access: read
      description: "Get a specific VLAN group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_vlan_group:
      method: PATCH
      path: /ipam/vlan-groups/{id}/
      access: write
      description: "Update a VLAN group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        min_vid: { type: integer, in: body }
        max_vid: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_vlan_group:
      method: DELETE
      path: /ipam/vlan-groups/{id}/
      access: dangerous
      description: "Delete a VLAN group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_vrfs:
      method: GET
      path: /ipam/vrfs/
      access: read
      description: "List all VRFs (Virtual Routing and Forwarding instances)"
      params:
        name: { type: string, in: query }
        rd: { type: string, in: query, description: "Route distinguisher" }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_vrf:
      method: GET
      path: /ipam/vrfs/{id}/
      access: read
      description: "Get a specific VRF"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_vrf:
      method: POST
      path: /ipam/vrfs/
      access: write
      description: "Create a VRF"
      params:
        name: { type: string, in: body, required: true }
        rd: { type: string, in: body, description: "Route distinguisher" }
        tenant: { type: integer, in: body }
        enforce_unique: { type: boolean, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_vrf:
      method: PATCH
      path: /ipam/vrfs/{id}/
      access: write
      description: "Update a VRF"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        rd: { type: string, in: body }
        enforce_unique: { type: boolean, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_vrf:
      method: DELETE
      path: /ipam/vrfs/{id}/
      access: dangerous
      description: "Delete a VRF"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # IPAM -- RIRs, Aggregates, ASNs, Roles, Services
    # =========================================================================

    list_rirs:
      method: GET
      path: /ipam/rirs/
      access: read
      description: "List Regional Internet Registries (RIPE, ARIN, etc.)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_rir:
      method: POST
      path: /ipam/rirs/
      access: write
      description: "Create a Regional Internet Registry"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        is_private: { type: boolean, in: body, description: "Private RIR (e.g. RFC 1918)" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_aggregates:
      method: GET
      path: /ipam/aggregates/
      access: read
      description: "List aggregate prefixes (top-level allocations from RIRs)"
      params:
        rir: { type: string, in: query }
        prefix: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_aggregate:
      method: POST
      path: /ipam/aggregates/
      access: write
      description: "Create an aggregate prefix (top-level RIR allocation)"
      params:
        prefix: { type: string, in: body, required: true, description: "CIDR notation (e.g. 10.0.0.0/8)" }
        rir: { type: integer, in: body, required: true }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_asns:
      method: GET
      path: /ipam/asns/
      access: read
      description: "List Autonomous System Numbers"
      params:
        asn: { type: integer, in: query }
        rir: { type: string, in: query }
        tenant: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_asn:
      method: POST
      path: /ipam/asns/
      access: write
      description: "Create an Autonomous System Number"
      params:
        asn: { type: integer, in: body, required: true, description: "32-bit ASN" }
        rir: { type: integer, in: body, required: true }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_ipam_roles:
      method: GET
      path: /ipam/roles/
      access: read
      description: "List IPAM roles for prefixes and VLANs"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_ipam_role:
      method: POST
      path: /ipam/roles/
      access: write
      description: "Create an IPAM role for prefixes and VLANs"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_services:
      method: GET
      path: /ipam/services/
      access: read
      description: "List services running on devices or VMs (DNS, HTTP, SSH, etc.). NetBox 4.x uses parent_object filters."
      params:
        device: { type: string, in: query, description: "Filter by device name (legacy, may not work on 4.x)" }
        device_id: { type: integer, in: query, description: "Filter by device ID" }
        virtual_machine: { type: string, in: query, description: "Filter by VM name (legacy, may not work on 4.x)" }
        virtual_machine_id: { type: integer, in: query, description: "Filter by VM ID" }
        name: { type: string, in: query }
        protocol: { type: string, in: query }
        port: { type: integer, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_service:
      method: POST
      path: /ipam/services/
      access: write
      description: "Create a service entry on a device or VM. NetBox 4.x uses GenericForeignKey: set parent_object_type and parent_object_id instead of device/virtual_machine."
      params:
        parent_object_type: { type: string, in: body, required: true, description: "Content type: 'dcim.device' or 'virtualization.virtualmachine'" }
        parent_object_id: { type: integer, in: body, required: true, description: "ID of the parent device or VM" }
        name: { type: string, in: body, required: true }
        protocol: { type: string, in: body, required: true, description: "tcp or udp" }
        ports: { type: array, in: body, required: true, description: "Array of port numbers" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    get_service:
      method: GET
      path: /ipam/services/{id}/
      access: read
      description: "Get a specific service"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_service:
      method: PATCH
      path: /ipam/services/{id}/
      access: write
      description: "Update a service. Use parent_object_type + parent_object_id to reassign (NetBox 4.x GenericForeignKey)."
      params:
        id: { type: integer, in: path, required: true }
        parent_object_type: { type: string, in: body, description: "Content type: 'dcim.device' or 'virtualization.virtualmachine'" }
        parent_object_id: { type: integer, in: body, description: "ID of the parent device or VM" }
        name: { type: string, in: body }
        protocol: { type: string, in: body }
        ports: { type: array, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    delete_service:
      method: DELETE
      path: /ipam/services/{id}/
      access: write
      description: "Delete a service"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_service_templates:
      method: GET
      path: /ipam/service-templates/
      access: read
      description: "List service templates (reusable service definitions, e.g. 'web-https')"
      params:
        name: { type: string, in: query }
        protocol: { type: string, in: query }
        port: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_service_template:
      method: GET
      path: /ipam/service-templates/{id}/
      access: read
      description: "Get a specific service template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_service_template:
      method: POST
      path: /ipam/service-templates/
      access: write
      description: "Create a service template"
      params:
        name: { type: string, in: body, required: true }
        protocol: { type: string, in: body, required: true, description: "tcp, udp, sctp" }
        ports: { type: array, in: body, required: true, description: "List of port numbers, e.g. [80, 443]" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_service_template:
      method: PATCH
      path: /ipam/service-templates/{id}/
      access: write
      description: "Update a service template"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        protocol: { type: string, in: body }
        ports: { type: array, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_service_template:
      method: DELETE
      path: /ipam/service-templates/{id}/
      access: dangerous
      description: "Delete a service template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_route_targets:
      method: GET
      path: /ipam/route-targets/
      access: read
      description: "List BGP route targets (e.g. '65000:100', used for MPLS L3VPN import/export)"
      params:
        name: { type: string, in: query }
        tenant: { type: string, in: query }
        importing_vrf_id: { type: integer, in: query }
        exporting_vrf_id: { type: integer, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_route_target:
      method: GET
      path: /ipam/route-targets/{id}/
      access: read
      description: "Get a specific route target"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_route_target:
      method: POST
      path: /ipam/route-targets/
      access: write
      description: "Create a route target. Assign to VRFs via vrf.import_targets / vrf.export_targets."
      params:
        name: { type: string, in: body, required: true, description: "Route target name (e.g. '65000:100')" }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_route_target:
      method: PATCH
      path: /ipam/route-targets/{id}/
      access: write
      description: "Update a route target"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_route_target:
      method: DELETE
      path: /ipam/route-targets/{id}/
      access: dangerous
      description: "Delete a route target"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_asn_ranges:
      method: GET
      path: /ipam/asn-ranges/
      access: read
      description: "List ASN ranges (bounded ASN allocation pools)"
      params:
        name: { type: string, in: query }
        rir: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_asn_range:
      method: GET
      path: /ipam/asn-ranges/{id}/
      access: read
      description: "Get a specific ASN range"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_asn_range:
      method: POST
      path: /ipam/asn-ranges/
      access: write
      description: "Create an ASN range"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        rir: { type: integer, in: body, required: true }
        start: { type: integer, in: body, required: true }
        end: { type: integer, in: body, required: true }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_asn_range:
      method: PATCH
      path: /ipam/asn-ranges/{id}/
      access: write
      description: "Update an ASN range"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        rir: { type: integer, in: body }
        start: { type: integer, in: body }
        end: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_asn_range:
      method: DELETE
      path: /ipam/asn-ranges/{id}/
      access: dangerous
      description: "Delete an ASN range"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_available_asns:
      method: GET
      path: /ipam/asn-ranges/{id}/available-asns/
      access: read
      description: "List the next unallocated ASNs within a range. POST to the same path to claim ASNs."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    claim_asn:
      method: POST
      path: /ipam/asn-ranges/{id}/available-asns/
      access: write
      description: "Claim the next available ASN from a range and assign metadata"
      params:
        id: { type: integer, in: path, required: true }
        description: { type: string, in: body }
        tenant: { type: integer, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_available_prefixes:
      method: GET
      path: /ipam/prefixes/{id}/available-prefixes/
      access: read
      description: "List unallocated sub-prefixes within a prefix"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    claim_prefix:
      method: POST
      path: /ipam/prefixes/{id}/available-prefixes/
      access: write
      description: "Carve a new child prefix out of a parent. NetBox picks the next free block of prefix_length."
      params:
        id: { type: integer, in: path, required: true }
        prefix_length: { type: integer, in: body, required: true, description: "Mask length for the new child prefix (e.g. 26)" }
        status: { type: string, in: body }
        site: { type: integer, in: body }
        vrf: { type: integer, in: body }
        tenant: { type: integer, in: body }
        role: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_available_ips_in_range:
      method: GET
      path: /ipam/ip-ranges/{id}/available-ips/
      access: read
      description: "List free IPs within an IP range"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_available_vlans:
      method: GET
      path: /ipam/vlan-groups/{id}/available-vlans/
      access: read
      description: "List the next unallocated VIDs in a VLAN group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    claim_vlan:
      method: POST
      path: /ipam/vlan-groups/{id}/available-vlans/
      access: write
      description: "Claim the next available VID from a VLAN group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body, required: true }
        status: { type: string, in: body }
        tenant: { type: integer, in: body }
        role: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_ip_range:
      method: GET
      path: /ipam/ip-ranges/{id}/
      access: read
      description: "Get a specific IP range"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_ip_range:
      method: PATCH
      path: /ipam/ip-ranges/{id}/
      access: write
      description: "Update an IP range"
      params:
        id: { type: integer, in: path, required: true }
        start_address: { type: string, in: body }
        end_address: { type: string, in: body }
        vrf: { type: integer, in: body }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_ip_range:
      method: DELETE
      path: /ipam/ip-ranges/{id}/
      access: dangerous
      description: "Delete an IP range"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_aggregate:
      method: GET
      path: /ipam/aggregates/{id}/
      access: read
      description: "Get a specific aggregate"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_aggregate:
      method: PATCH
      path: /ipam/aggregates/{id}/
      access: write
      description: "Update an aggregate"
      params:
        id: { type: integer, in: path, required: true }
        prefix: { type: string, in: body }
        rir: { type: integer, in: body }
        tenant: { type: integer, in: body }
        date_added: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_aggregate:
      method: DELETE
      path: /ipam/aggregates/{id}/
      access: dangerous
      description: "Delete an aggregate"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_asn:
      method: GET
      path: /ipam/asns/{id}/
      access: read
      description: "Get a specific ASN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_asn:
      method: PATCH
      path: /ipam/asns/{id}/
      access: write
      description: "Update an ASN"
      params:
        id: { type: integer, in: path, required: true }
        asn: { type: integer, in: body }
        rir: { type: integer, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_asn:
      method: DELETE
      path: /ipam/asns/{id}/
      access: dangerous
      description: "Delete an ASN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_rir:
      method: GET
      path: /ipam/rirs/{id}/
      access: read
      description: "Get a specific RIR (Regional Internet Registry, e.g. RIPE, ARIN)"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_rir:
      method: PATCH
      path: /ipam/rirs/{id}/
      access: write
      description: "Update a RIR"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        is_private: { type: boolean, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_rir:
      method: DELETE
      path: /ipam/rirs/{id}/
      access: dangerous
      description: "Delete a RIR"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # IPAM -- VLAN Translations
    # =========================================================================

    list_vlan_translation_policies:
      method: GET
      path: /ipam/vlan-translation-policies/
      access: read
      description: "List VLAN translation policies (named sets of 1:1 VID mappings, NetBox 4.0+)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_vlan_translation_policy:
      method: GET
      path: /ipam/vlan-translation-policies/{id}/
      access: read
      description: "Get a specific VLAN translation policy"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_vlan_translation_policy:
      method: POST
      path: /ipam/vlan-translation-policies/
      access: write
      description: "Create a VLAN translation policy"
      params:
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_vlan_translation_policy:
      method: PATCH
      path: /ipam/vlan-translation-policies/{id}/
      access: write
      description: "Update a VLAN translation policy"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_vlan_translation_policy:
      method: DELETE
      path: /ipam/vlan-translation-policies/{id}/
      access: dangerous
      description: "Delete a VLAN translation policy"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_vlan_translation_rules:
      method: GET
      path: /ipam/vlan-translation-rules/
      access: read
      description: "List VLAN translation rules (individual local-VID to remote-VID mappings within a policy)"
      params:
        policy: { type: integer, in: query }
        policy_id: { type: integer, in: query }
        local_vid: { type: integer, in: query }
        remote_vid: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_vlan_translation_rule:
      method: GET
      path: /ipam/vlan-translation-rules/{id}/
      access: read
      description: "Get a specific VLAN translation rule"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_vlan_translation_rule:
      method: POST
      path: /ipam/vlan-translation-rules/
      access: write
      description: "Create a VLAN translation rule"
      params:
        policy: { type: integer, in: body, required: true }
        local_vid: { type: integer, in: body, required: true }
        remote_vid: { type: integer, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_vlan_translation_rule:
      method: PATCH
      path: /ipam/vlan-translation-rules/{id}/
      access: write
      description: "Update a VLAN translation rule"
      params:
        id: { type: integer, in: path, required: true }
        policy: { type: integer, in: body }
        local_vid: { type: integer, in: body }
        remote_vid: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_vlan_translation_rule:
      method: DELETE
      path: /ipam/vlan-translation-rules/{id}/
      access: dangerous
      description: "Delete a VLAN translation rule"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # IPAM -- FHRP Groups & Assignments
    # =========================================================================

    list_fhrp_groups:
      method: GET
      path: /ipam/fhrp-groups/
      access: read
      description: "List FHRP (First Hop Redundancy Protocol) groups. FHRP groups represent virtual IP failover configurations using VRRP, HSRP, GLBP, or CARP. Each group has a protocol, numeric group_id, and optional name. IP addresses are assigned to groups separately."
      params:
        name: { type: string, in: query }
        protocol: { type: string, in: query, description: "Filter by protocol: vrrp2, vrrp3, hsrp, carp, glbp" }
        group_id: { type: integer, in: query, description: "Filter by numeric group identifier" }
        auth_type: { type: string, in: query, description: "Filter by authentication type: plaintext, md5" }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_fhrp_group:
      method: GET
      path: /ipam/fhrp-groups/{id}/
      access: read
      description: "Get a specific FHRP group by ID. Returns protocol, group_id, name, auth_type, auth_key, and assigned IP addresses."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_fhrp_group:
      method: POST
      path: /ipam/fhrp-groups/
      access: write
      description: "Create an FHRP group. Requires protocol and group_id. Virtual IP addresses can be created alongside the group or assigned afterward via IP address objects."
      params:
        protocol: { type: string, in: body, required: true, description: "FHRP protocol: vrrp2, vrrp3, hsrp, carp, glbp" }
        group_id: { type: integer, in: body, required: true, description: "Numeric group identifier (e.g. VRID for VRRP)" }
        name: { type: string, in: body, description: "Optional display name for the group" }
        auth_type: { type: string, in: body, description: "Authentication type: plaintext, md5. Leave empty for none." }
        auth_key: { type: string, in: body, description: "Shared authentication key (stored in plaintext in NetBox DB)" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body }
      pagination: none

    update_fhrp_group:
      method: PATCH
      path: /ipam/fhrp-groups/{id}/
      access: write
      description: "Update an FHRP group."
      params:
        id: { type: integer, in: path, required: true }
        protocol: { type: string, in: body, description: "FHRP protocol: vrrp2, vrrp3, hsrp, carp, glbp" }
        group_id: { type: integer, in: body, description: "Numeric group identifier" }
        name: { type: string, in: body }
        auth_type: { type: string, in: body, description: "Authentication type: plaintext, md5" }
        auth_key: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body }
      pagination: none

    delete_fhrp_group:
      method: DELETE
      path: /ipam/fhrp-groups/{id}/
      access: dangerous
      description: "Delete an FHRP group. This also removes all group assignments."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_fhrp_group_assignments:
      method: GET
      path: /ipam/fhrp-group-assignments/
      access: read
      description: "List FHRP group assignments — links between FHRP groups and device/VM interfaces. Each assignment has a priority (0-255) determining master/primary election."
      params:
        group_id: { type: integer, in: query, description: "Filter by FHRP group ID" }
        interface_type: { type: string, in: query, description: "Content type filter: dcim.interface or virtualization.vminterface" }
        interface_id: { type: integer, in: query, description: "Filter by interface ID" }
        device: { type: string, in: query, description: "Filter by device name (via interface)" }
        device_id: { type: integer, in: query, description: "Filter by device ID (via interface)" }
        virtual_machine: { type: string, in: query, description: "Filter by VM name (via interface)" }
        virtual_machine_id: { type: integer, in: query, description: "Filter by VM ID (via interface)" }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_fhrp_group_assignment:
      method: GET
      path: /ipam/fhrp-group-assignments/{id}/
      access: read
      description: "Get a specific FHRP group assignment by ID."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_fhrp_group_assignment:
      method: POST
      path: /ipam/fhrp-group-assignments/
      access: write
      description: "Assign an FHRP group to a device or VM interface. Priority (0-255) determines master/primary election — higher priority = more likely to be elected master."
      params:
        group: { type: integer, in: body, required: true, description: "FHRP group ID" }
        interface_type: { type: string, in: body, required: true, description: "Content type: 'dcim.interface' or 'virtualization.vminterface'" }
        interface_id: { type: integer, in: body, required: true, description: "ID of the device or VM interface" }
        priority: { type: integer, in: body, required: true, description: "Election priority 0-255 (higher = more likely master)" }
      pagination: none

    update_fhrp_group_assignment:
      method: PATCH
      path: /ipam/fhrp-group-assignments/{id}/
      access: write
      description: "Update an FHRP group assignment (e.g. change priority or reassign to a different interface)."
      params:
        id: { type: integer, in: path, required: true }
        group: { type: integer, in: body, description: "FHRP group ID" }
        interface_type: { type: string, in: body, description: "Content type: 'dcim.interface' or 'virtualization.vminterface'" }
        interface_id: { type: integer, in: body, description: "ID of the device or VM interface" }
        priority: { type: integer, in: body, description: "Election priority 0-255" }
      pagination: none

    delete_fhrp_group_assignment:
      method: DELETE
      path: /ipam/fhrp-group-assignments/{id}/
      access: dangerous
      description: "Delete an FHRP group assignment — removes the interface from the FHRP group."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # VIRTUALIZATION -- Clusters & VMs
    # =========================================================================

    list_cluster_types:
      method: GET
      path: /virtualization/cluster-types/
      access: read
      description: "List cluster types (VMware, Proxmox, XCP-ng, etc.)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_cluster_type:
      method: POST
      path: /virtualization/cluster-types/
      access: write
      description: "Create a cluster type (e.g. VMware, Proxmox, Linode, XCP-ng)"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    list_cluster_groups:
      method: GET
      path: /virtualization/cluster-groups/
      access: read
      description: "List cluster groups"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_cluster_group:
      method: POST
      path: /virtualization/cluster-groups/
      access: write
      description: "Create a cluster group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_cluster_group:
      method: GET
      path: /virtualization/cluster-groups/{id}/
      access: read
      description: "Get a specific cluster group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_cluster_group:
      method: PATCH
      path: /virtualization/cluster-groups/{id}/
      access: write
      description: "Update a cluster group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_cluster_group:
      method: DELETE
      path: /virtualization/cluster-groups/{id}/
      access: dangerous
      description: "Delete a cluster group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_clusters:
      method: GET
      path: /virtualization/clusters/
      access: read
      description: "List all virtualization clusters"
      params:
        name: { type: string, in: query }
        type: { type: string, in: query }
        group: { type: string, in: query }
        site: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_cluster:
      method: GET
      path: /virtualization/clusters/{id}/
      access: read
      description: "Get a specific cluster"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_cluster:
      method: POST
      path: /virtualization/clusters/
      access: write
      description: "Create a virtualization cluster"
      params:
        name: { type: string, in: body, required: true }
        type: { type: integer, in: body, required: true }
        group: { type: integer, in: body }
        site: { type: integer, in: body }
        status: { type: string, in: body, description: "active, planned, decommissioning, offline" }
        scope_type: { type: string, in: body, description: "Scope type: dcim.site, dcim.location, dcim.region, etc." }
        scope_id: { type: integer, in: body, description: "ID of the scoped object" }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_cluster:
      method: PATCH
      path: /virtualization/clusters/{id}/
      access: write
      description: "Update a cluster"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        group: { type: integer, in: body }
        site: { type: integer, in: body }
        status: { type: string, in: body, description: "active, planned, decommissioning, offline" }
        scope_type: { type: string, in: body, description: "Scope type: dcim.site, dcim.location, dcim.region, etc." }
        scope_id: { type: integer, in: body, description: "ID of the scoped object" }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_cluster:
      method: DELETE
      path: /virtualization/clusters/{id}/
      access: dangerous
      description: "Delete a cluster"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_machines:
      method: GET
      path: /virtualization/virtual-machines/
      access: read
      description: "List all virtual machines"
      params:
        name: { type: string, in: query }
        cluster: { type: string, in: query }
        site: { type: string, in: query }
        status: { type: string, in: query, description: "offline, active, planned, staged, failed, decommissioning" }
        device: { type: string, in: query }
        role: { type: string, in: query }
        platform: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_virtual_machine:
      method: GET
      path: /virtualization/virtual-machines/{id}/
      access: read
      description: "Get a specific virtual machine"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_virtual_machine:
      method: POST
      path: /virtualization/virtual-machines/
      access: write
      description: "Create a virtual machine"
      params:
        name: { type: string, in: body, required: true }
        cluster: { type: integer, in: body, required: true }
        status: { type: string, in: body }
        role: { type: integer, in: body }
        platform: { type: integer, in: body }
        tenant: { type: integer, in: body }
        vcpus: { type: number, in: body }
        memory: { type: integer, in: body, description: "Memory in MB" }
        disk: { type: integer, in: body, description: "Disk size in GB" }
        site: { type: integer, in: body }
        device: { type: integer, in: body, description: "ID of the host device" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    update_virtual_machine:
      method: PATCH
      path: /virtualization/virtual-machines/{id}/
      access: write
      description: "Update a virtual machine"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        cluster: { type: integer, in: body }
        site: { type: integer, in: body }
        device: { type: integer, in: body, description: "ID of the host device" }
        status: { type: string, in: body }
        vcpus: { type: number, in: body }
        memory: { type: integer, in: body }
        disk: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        platform: { type: integer, in: body }
        role: { type: integer, in: body }
        tenant: { type: integer, in: body }
        primary_ip4: { type: integer, in: body, description: "ID of the primary IPv4 address" }
        primary_ip6: { type: integer, in: body, description: "ID of the primary IPv6 address" }
        tags: { type: array, in: body }
        custom_fields: { type: object, in: body, description: "Custom field values as key-value pairs" }
      pagination: none

    delete_virtual_machine:
      method: DELETE
      path: /virtualization/virtual-machines/{id}/
      access: dangerous
      description: "Delete a virtual machine"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_vm_interfaces:
      method: GET
      path: /virtualization/interfaces/
      access: read
      description: "List virtual machine interfaces"
      params:
        virtual_machine: { type: string, in: query }
        virtual_machine_id: { type: integer, in: query }
        name: { type: string, in: query }
        enabled: { type: boolean, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_vm_interface:
      method: POST
      path: /virtualization/interfaces/
      access: write
      description: "Create a VM interface"
      params:
        virtual_machine: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        enabled: { type: boolean, in: body }
        mtu: { type: integer, in: body }
        primary_mac_address: { type: integer, in: body, description: "Primary MAC address object ID. NetBox 4.x stores MACs as separate objects: create_mac_address first (assigned_object_type virtualization.vminterface), then set its ID here. The interface's mac_address field itself is read-only." }
        parent: { type: integer, in: body, description: "Parent interface ID" }
        bridge: { type: integer, in: body, description: "Bridge interface ID" }
        vrf: { type: integer, in: body, description: "VRF assignment" }
        description: { type: string, in: body }
        mode: { type: string, in: body }
        untagged_vlan: { type: integer, in: body }
        tagged_vlans: { type: array, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_vm_interface:
      method: GET
      path: /virtualization/interfaces/{id}/
      access: read
      description: "Get a specific VM interface"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_vm_interface:
      method: PATCH
      path: /virtualization/interfaces/{id}/
      access: write
      description: "Update a VM interface"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        enabled: { type: boolean, in: body }
        mtu: { type: integer, in: body }
        primary_mac_address: { type: integer, in: body, description: "Primary MAC address object ID. NetBox 4.x stores MACs as separate objects: create_mac_address first (assigned_object_type virtualization.vminterface), then set its ID here. The interface's mac_address field itself is read-only." }
        parent: { type: integer, in: body, description: "Parent interface ID" }
        bridge: { type: integer, in: body, description: "Bridge interface ID" }
        vrf: { type: integer, in: body, description: "VRF assignment" }
        description: { type: string, in: body }
        mode: { type: string, in: body }
        untagged_vlan: { type: integer, in: body }
        tagged_vlans: { type: array, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_vm_interface:
      method: DELETE
      path: /virtualization/interfaces/{id}/
      access: write
      description: "Delete a VM interface"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_disks:
      method: GET
      path: /virtualization/virtual-disks/
      access: read
      description: "List virtual disks"
      params:
        virtual_machine: { type: string, in: query }
        virtual_machine_id: { type: integer, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_virtual_disk:
      method: POST
      path: /virtualization/virtual-disks/
      access: write
      description: "Create a virtual disk"
      params:
        virtual_machine: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        size: { type: integer, in: body, required: true, description: "Disk size in GB" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_virtual_disk:
      method: GET
      path: /virtualization/virtual-disks/{id}/
      access: read
      description: "Get a specific virtual disk"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_virtual_disk:
      method: PATCH
      path: /virtualization/virtual-disks/{id}/
      access: write
      description: "Update a virtual disk"
      params:
        id: { type: integer, in: path, required: true }
        virtual_machine: { type: integer, in: body }
        name: { type: string, in: body }
        size: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_virtual_disk:
      method: DELETE
      path: /virtualization/virtual-disks/{id}/
      access: dangerous
      description: "Delete a virtual disk"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_machine_types:
      method: GET
      path: /virtualization/virtual-machine-types/
      access: read
      description: "List virtual machine types (NetBox 4.2+, model definitions like AWS EC2 'm5.xlarge')"
      params:
        manufacturer: { type: string, in: query }
        manufacturer_id: { type: integer, in: query }
        model: { type: string, in: query }
        slug: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_virtual_machine_type:
      method: GET
      path: /virtualization/virtual-machine-types/{id}/
      access: read
      description: "Get a specific VM type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_virtual_machine_type:
      method: POST
      path: /virtualization/virtual-machine-types/
      access: write
      description: "Create a virtual machine type"
      params:
        manufacturer: { type: integer, in: body, required: true }
        model: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_virtual_machine_type:
      method: PATCH
      path: /virtualization/virtual-machine-types/{id}/
      access: write
      description: "Update a virtual machine type"
      params:
        id: { type: integer, in: path, required: true }
        manufacturer: { type: integer, in: body }
        model: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_virtual_machine_type:
      method: DELETE
      path: /virtualization/virtual-machine-types/{id}/
      access: dangerous
      description: "Delete a virtual machine type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # TENANCY
    # =========================================================================

    list_tenants:
      method: GET
      path: /tenancy/tenants/
      access: read
      description: "List all tenants (customers, departments, teams)"
      params:
        name: { type: string, in: query }
        group: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_tenant:
      method: GET
      path: /tenancy/tenants/{id}/
      access: read
      description: "Get a specific tenant"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_tenant:
      method: POST
      path: /tenancy/tenants/
      access: write
      description: "Create a tenant"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        group: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_tenant:
      method: PATCH
      path: /tenancy/tenants/{id}/
      access: write
      description: "Update a tenant"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        group: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_tenant:
      method: DELETE
      path: /tenancy/tenants/{id}/
      access: dangerous
      description: "Delete a tenant"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_tenant_groups:
      method: GET
      path: /tenancy/tenant-groups/
      access: read
      description: "List tenant groups"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_tenant_group:
      method: POST
      path: /tenancy/tenant-groups/
      access: write
      description: "Create a tenant group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_tenant_group:
      method: GET
      path: /tenancy/tenant-groups/{id}/
      access: read
      description: "Get a specific tenant group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_tenant_group:
      method: PATCH
      path: /tenancy/tenant-groups/{id}/
      access: write
      description: "Update a tenant group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_tenant_group:
      method: DELETE
      path: /tenancy/tenant-groups/{id}/
      access: dangerous
      description: "Delete a tenant group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_contacts:
      method: GET
      path: /tenancy/contacts/
      access: read
      description: "List all contacts"
      params:
        name: { type: string, in: query }
        group: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_contact:
      method: POST
      path: /tenancy/contacts/
      access: write
      description: "Create a contact"
      params:
        name: { type: string, in: body, required: true }
        group: { type: integer, in: body }
        title: { type: string, in: body }
        phone: { type: string, in: body }
        email: { type: string, in: body }
        address: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_contact:
      method: GET
      path: /tenancy/contacts/{id}/
      access: read
      description: "Get a specific contact"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_contact:
      method: PATCH
      path: /tenancy/contacts/{id}/
      access: write
      description: "Update a contact"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        title: { type: string, in: body }
        phone: { type: string, in: body }
        email: { type: string, in: body }
        address: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_contact:
      method: DELETE
      path: /tenancy/contacts/{id}/
      access: dangerous
      description: "Delete a contact"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_contact_roles:
      method: GET
      path: /tenancy/contact-roles/
      access: read
      description: "List contact roles (admin, NOC, billing, etc.)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_contact_role:
      method: POST
      path: /tenancy/contact-roles/
      access: write
      description: "Create a contact role"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_contact_role:
      method: GET
      path: /tenancy/contact-roles/{id}/
      access: read
      description: "Get a specific contact role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_contact_role:
      method: PATCH
      path: /tenancy/contact-roles/{id}/
      access: write
      description: "Update a contact role"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_contact_role:
      method: DELETE
      path: /tenancy/contact-roles/{id}/
      access: dangerous
      description: "Delete a contact role"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_contact_groups:
      method: GET
      path: /tenancy/contact-groups/
      access: read
      description: "List contact groups (hierarchical grouping of contacts)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        parent: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_contact_group:
      method: GET
      path: /tenancy/contact-groups/{id}/
      access: read
      description: "Get a specific contact group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_contact_group:
      method: POST
      path: /tenancy/contact-groups/
      access: write
      description: "Create a contact group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_contact_group:
      method: PATCH
      path: /tenancy/contact-groups/{id}/
      access: write
      description: "Update a contact group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_contact_group:
      method: DELETE
      path: /tenancy/contact-groups/{id}/
      access: dangerous
      description: "Delete a contact group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_contact_assignments:
      method: GET
      path: /tenancy/contact-assignments/
      access: read
      description: "List contact assignments (links between contacts and any NetBox object)"
      params:
        object_type: { type: string, in: query, description: "e.g. dcim.device, ipam.prefix, circuits.circuit" }
        object_id: { type: integer, in: query }
        contact: { type: integer, in: query }
        contact_id: { type: integer, in: query }
        role: { type: integer, in: query }
        role_id: { type: integer, in: query }
        priority: { type: string, in: query, description: "primary, secondary, tertiary, inactive" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_contact_assignment:
      method: GET
      path: /tenancy/contact-assignments/{id}/
      access: read
      description: "Get a specific contact assignment"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_contact_assignment:
      method: POST
      path: /tenancy/contact-assignments/
      access: write
      description: "Assign a contact to an object (device, circuit, etc.)"
      params:
        object_type: { type: string, in: body, required: true, description: "e.g. dcim.device, circuits.circuit" }
        object_id: { type: integer, in: body, required: true }
        contact: { type: integer, in: body, required: true }
        role: { type: integer, in: body, required: true, description: "ID of the contact role. The NetBox data model requires it -- omitting it returns HTTP 400." }
        priority: { type: string, in: body, description: "primary, secondary, tertiary, inactive" }
        tags: { type: array, in: body }
      pagination: none

    update_contact_assignment:
      method: PATCH
      path: /tenancy/contact-assignments/{id}/
      access: write
      description: "Update a contact assignment"
      params:
        id: { type: integer, in: path, required: true }
        contact: { type: integer, in: body }
        role: { type: integer, in: body }
        priority: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_contact_assignment:
      method: DELETE
      path: /tenancy/contact-assignments/{id}/
      access: dangerous
      description: "Delete a contact assignment"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # CIRCUITS
    # =========================================================================

    list_providers:
      method: GET
      path: /circuits/providers/
      access: read
      description: "List circuit providers (ISPs, carriers)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_provider:
      method: POST
      path: /circuits/providers/
      access: write
      description: "Create a circuit provider"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        asns: { type: array, in: body, description: "Array of ASN IDs" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_provider:
      method: GET
      path: /circuits/providers/{id}/
      access: read
      description: "Get a specific provider"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_provider:
      method: PATCH
      path: /circuits/providers/{id}/
      access: write
      description: "Update a provider"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_provider:
      method: DELETE
      path: /circuits/providers/{id}/
      access: dangerous
      description: "Delete a provider"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_circuit_types:
      method: GET
      path: /circuits/circuit-types/
      access: read
      description: "List circuit types (Internet, MPLS, dark fiber, etc.)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_circuit_type:
      method: POST
      path: /circuits/circuit-types/
      access: write
      description: "Create a circuit type"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_circuit_type:
      method: GET
      path: /circuits/circuit-types/{id}/
      access: read
      description: "Get a specific circuit type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_circuit_type:
      method: PATCH
      path: /circuits/circuit-types/{id}/
      access: write
      description: "Update a circuit type"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_circuit_type:
      method: DELETE
      path: /circuits/circuit-types/{id}/
      access: dangerous
      description: "Delete a circuit type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_circuits:
      method: GET
      path: /circuits/circuits/
      access: read
      description: "List all circuits"
      params:
        cid: { type: string, in: query, description: "Circuit ID" }
        provider: { type: string, in: query }
        type: { type: string, in: query }
        site: { type: string, in: query }
        status: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_circuit:
      method: GET
      path: /circuits/circuits/{id}/
      access: read
      description: "Get a specific circuit"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_circuit:
      method: POST
      path: /circuits/circuits/
      access: write
      description: "Create a circuit"
      params:
        cid: { type: string, in: body, required: true, description: "Circuit ID (provider's reference)" }
        provider: { type: integer, in: body, required: true }
        type: { type: integer, in: body, required: true }
        status: { type: string, in: body }
        tenant: { type: integer, in: body }
        commit_rate: { type: integer, in: body, description: "Committed rate in Kbps" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_circuit:
      method: PATCH
      path: /circuits/circuits/{id}/
      access: write
      description: "Update a circuit"
      params:
        id: { type: integer, in: path, required: true }
        cid: { type: string, in: body }
        status: { type: string, in: body }
        commit_rate: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_circuit:
      method: DELETE
      path: /circuits/circuits/{id}/
      access: dangerous
      description: "Delete a circuit"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_circuit_terminations:
      method: GET
      path: /circuits/circuit-terminations/
      access: read
      description: "List circuit terminations (A-side and Z-side endpoints)"
      params:
        circuit_id: { type: integer, in: query }
        site: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_circuit_termination:
      method: POST
      path: /circuits/circuit-terminations/
      access: write
      description: "Create a circuit termination (A or Z side)"
      params:
        circuit: { type: integer, in: body, required: true }
        term_side: { type: string, in: body, required: true, description: "A or Z" }
        site: { type: integer, in: body }
        port_speed: { type: integer, in: body, description: "Port speed in Kbps" }
        upstream_speed: { type: integer, in: body, description: "Upstream speed in Kbps" }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    get_circuit_termination:
      method: GET
      path: /circuits/circuit-terminations/{id}/
      access: read
      description: "Get a specific circuit termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_circuit_termination:
      method: PATCH
      path: /circuits/circuit-terminations/{id}/
      access: write
      description: "Update a circuit termination"
      params:
        id: { type: integer, in: path, required: true }
        site: { type: integer, in: body }
        port_speed: { type: integer, in: body }
        upstream_speed: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_circuit_termination:
      method: DELETE
      path: /circuits/circuit-terminations/{id}/
      access: dangerous
      description: "Delete a circuit termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    paths_circuit_termination:
      method: GET
      path: /circuits/circuit-terminations/{id}/paths/
      access: read
      description: "Trace cable paths from a circuit termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_provider_accounts:
      method: GET
      path: /circuits/provider-accounts/
      access: read
      description: "List provider accounts (a customer's account number with a provider)"
      params:
        name: { type: string, in: query }
        account: { type: string, in: query }
        provider: { type: string, in: query }
        provider_id: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_provider_account:
      method: GET
      path: /circuits/provider-accounts/{id}/
      access: read
      description: "Get a specific provider account"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_provider_account:
      method: POST
      path: /circuits/provider-accounts/
      access: write
      description: "Create a provider account"
      params:
        provider: { type: integer, in: body, required: true }
        name: { type: string, in: body }
        account: { type: string, in: body, required: true }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_provider_account:
      method: PATCH
      path: /circuits/provider-accounts/{id}/
      access: write
      description: "Update a provider account"
      params:
        id: { type: integer, in: path, required: true }
        provider: { type: integer, in: body }
        name: { type: string, in: body }
        account: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_provider_account:
      method: DELETE
      path: /circuits/provider-accounts/{id}/
      access: dangerous
      description: "Delete a provider account"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_provider_networks:
      method: GET
      path: /circuits/provider-networks/
      access: read
      description: "List provider networks (the far end of a circuit -- a provider's MPLS cloud, peering fabric, etc.)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        provider: { type: string, in: query }
        provider_id: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_provider_network:
      method: GET
      path: /circuits/provider-networks/{id}/
      access: read
      description: "Get a specific provider network"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_provider_network:
      method: POST
      path: /circuits/provider-networks/
      access: write
      description: "Create a provider network"
      params:
        provider: { type: integer, in: body, required: true }
        name: { type: string, in: body, required: true }
        service_id: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_provider_network:
      method: PATCH
      path: /circuits/provider-networks/{id}/
      access: write
      description: "Update a provider network"
      params:
        id: { type: integer, in: path, required: true }
        provider: { type: integer, in: body }
        name: { type: string, in: body }
        service_id: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_provider_network:
      method: DELETE
      path: /circuits/provider-networks/{id}/
      access: dangerous
      description: "Delete a provider network"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_circuit_groups:
      method: GET
      path: /circuits/circuit-groups/
      access: read
      description: "List circuit groups (logical grouping of related circuits, e.g. SD-WAN underlays)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_circuit_group:
      method: GET
      path: /circuits/circuit-groups/{id}/
      access: read
      description: "Get a specific circuit group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_circuit_group:
      method: POST
      path: /circuits/circuit-groups/
      access: write
      description: "Create a circuit group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_circuit_group:
      method: PATCH
      path: /circuits/circuit-groups/{id}/
      access: write
      description: "Update a circuit group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_circuit_group:
      method: DELETE
      path: /circuits/circuit-groups/{id}/
      access: dangerous
      description: "Delete a circuit group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_circuit_group_assignments:
      method: GET
      path: /circuits/circuit-group-assignments/
      access: read
      description: "List circuit-to-group assignments with priorities"
      params:
        group: { type: integer, in: query }
        group_id: { type: integer, in: query }
        member_type: { type: string, in: query, description: "e.g. circuits.circuit, circuits.virtualcircuit" }
        member_id: { type: integer, in: query }
        priority: { type: string, in: query, description: "primary, secondary, tertiary, inactive" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_circuit_group_assignment:
      method: GET
      path: /circuits/circuit-group-assignments/{id}/
      access: read
      description: "Get a specific circuit group assignment"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_circuit_group_assignment:
      method: POST
      path: /circuits/circuit-group-assignments/
      access: write
      description: "Assign a circuit (or virtual circuit) to a circuit group"
      params:
        group: { type: integer, in: body, required: true }
        member_type: { type: string, in: body, required: true, description: "circuits.circuit or circuits.virtualcircuit" }
        member_id: { type: integer, in: body, required: true }
        priority: { type: string, in: body, description: "primary, secondary, tertiary, inactive" }
        tags: { type: array, in: body }
      pagination: none

    update_circuit_group_assignment:
      method: PATCH
      path: /circuits/circuit-group-assignments/{id}/
      access: write
      description: "Update a circuit group assignment"
      params:
        id: { type: integer, in: path, required: true }
        priority: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_circuit_group_assignment:
      method: DELETE
      path: /circuits/circuit-group-assignments/{id}/
      access: dangerous
      description: "Delete a circuit group assignment"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_circuit_types:
      method: GET
      path: /circuits/virtual-circuit-types/
      access: read
      description: "List virtual circuit types (classification of virtual circuits, NetBox 4.2+)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_virtual_circuit_type:
      method: GET
      path: /circuits/virtual-circuit-types/{id}/
      access: read
      description: "Get a specific virtual circuit type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_virtual_circuit_type:
      method: POST
      path: /circuits/virtual-circuit-types/
      access: write
      description: "Create a virtual circuit type"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        color: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_virtual_circuit_type:
      method: PATCH
      path: /circuits/virtual-circuit-types/{id}/
      access: write
      description: "Update a virtual circuit type"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        color: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_virtual_circuit_type:
      method: DELETE
      path: /circuits/virtual-circuit-types/{id}/
      access: dangerous
      description: "Delete a virtual circuit type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_circuits:
      method: GET
      path: /circuits/virtual-circuits/
      access: read
      description: "List virtual circuits (logical end-to-end paths that run over a provider network, NetBox 4.2+)"
      params:
        cid: { type: string, in: query }
        provider_network: { type: string, in: query }
        provider_network_id: { type: integer, in: query }
        type: { type: string, in: query }
        status: { type: string, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_virtual_circuit:
      method: GET
      path: /circuits/virtual-circuits/{id}/
      access: read
      description: "Get a specific virtual circuit"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_virtual_circuit:
      method: POST
      path: /circuits/virtual-circuits/
      access: write
      description: "Create a virtual circuit"
      params:
        cid: { type: string, in: body, required: true, description: "Circuit ID, the provider's reference" }
        provider_network: { type: integer, in: body, required: true }
        provider_account: { type: integer, in: body }
        type: { type: integer, in: body, required: true }
        status: { type: string, in: body, description: "planned, provisioning, active, offline, deprovisioning, decommissioned" }
        tenant: { type: integer, in: body }
        group: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_virtual_circuit:
      method: PATCH
      path: /circuits/virtual-circuits/{id}/
      access: write
      description: "Update a virtual circuit"
      params:
        id: { type: integer, in: path, required: true }
        cid: { type: string, in: body }
        provider_network: { type: integer, in: body }
        provider_account: { type: integer, in: body }
        type: { type: integer, in: body }
        status: { type: string, in: body }
        tenant: { type: integer, in: body }
        group: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_virtual_circuit:
      method: DELETE
      path: /circuits/virtual-circuits/{id}/
      access: dangerous
      description: "Delete a virtual circuit"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_virtual_circuit_terminations:
      method: GET
      path: /circuits/virtual-circuit-terminations/
      access: read
      description: "List virtual circuit terminations (endpoints of virtual circuits on interfaces)"
      params:
        virtual_circuit: { type: integer, in: query }
        virtual_circuit_id: { type: integer, in: query }
        role: { type: string, in: query, description: "peer, hub, spoke" }
        interface: { type: integer, in: query }
        interface_id: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_virtual_circuit_termination:
      method: GET
      path: /circuits/virtual-circuit-terminations/{id}/
      access: read
      description: "Get a specific virtual circuit termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_virtual_circuit_termination:
      method: POST
      path: /circuits/virtual-circuit-terminations/
      access: write
      description: "Terminate a virtual circuit on a physical interface"
      params:
        virtual_circuit: { type: integer, in: body, required: true }
        role: { type: string, in: body, description: "peer, hub, spoke" }
        interface: { type: integer, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_virtual_circuit_termination:
      method: PATCH
      path: /circuits/virtual-circuit-terminations/{id}/
      access: write
      description: "Update a virtual circuit termination"
      params:
        id: { type: integer, in: path, required: true }
        role: { type: string, in: body }
        interface: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_virtual_circuit_termination:
      method: DELETE
      path: /circuits/virtual-circuit-terminations/{id}/
      access: dangerous
      description: "Delete a virtual circuit termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # WIRELESS
    # =========================================================================

    list_wireless_lan_groups:
      method: GET
      path: /wireless/wireless-lan-groups/
      access: read
      description: "List wireless LAN groups (hierarchical grouping of SSIDs)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        parent: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_wireless_lan_group:
      method: GET
      path: /wireless/wireless-lan-groups/{id}/
      access: read
      description: "Get a specific wireless LAN group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_wireless_lan_group:
      method: POST
      path: /wireless/wireless-lan-groups/
      access: write
      description: "Create a wireless LAN group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_wireless_lan_group:
      method: PATCH
      path: /wireless/wireless-lan-groups/{id}/
      access: write
      description: "Update a wireless LAN group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        parent: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_wireless_lan_group:
      method: DELETE
      path: /wireless/wireless-lan-groups/{id}/
      access: dangerous
      description: "Delete a wireless LAN group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_wireless_lans:
      method: GET
      path: /wireless/wireless-lans/
      access: read
      description: "List wireless LANs (SSIDs)"
      params:
        ssid: { type: string, in: query }
        group: { type: string, in: query }
        status: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_wireless_lan:
      method: GET
      path: /wireless/wireless-lans/{id}/
      access: read
      description: "Get a specific wireless LAN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_wireless_lan:
      method: POST
      path: /wireless/wireless-lans/
      access: write
      description: "Create a wireless LAN (SSID)"
      params:
        ssid: { type: string, in: body, required: true }
        status: { type: string, in: body, description: "active, reserved, disabled" }
        group: { type: integer, in: body }
        vlan: { type: integer, in: body }
        scope_type: { type: string, in: body, description: "dcim.location, dcim.region, dcim.site, dcim.sitegroup" }
        scope_id: { type: integer, in: body }
        auth_type: { type: string, in: body, description: "open, wep, wpa-personal, wpa-enterprise" }
        auth_cipher: { type: string, in: body, description: "auto, tkip, aes" }
        auth_psk: { type: string, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_wireless_lan:
      method: PATCH
      path: /wireless/wireless-lans/{id}/
      access: write
      description: "Update a wireless LAN"
      params:
        id: { type: integer, in: path, required: true }
        ssid: { type: string, in: body }
        status: { type: string, in: body }
        group: { type: integer, in: body }
        vlan: { type: integer, in: body }
        scope_type: { type: string, in: body }
        scope_id: { type: integer, in: body }
        auth_type: { type: string, in: body }
        auth_cipher: { type: string, in: body }
        auth_psk: { type: string, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_wireless_lan:
      method: DELETE
      path: /wireless/wireless-lans/{id}/
      access: dangerous
      description: "Delete a wireless LAN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_wireless_links:
      method: GET
      path: /wireless/wireless-links/
      access: read
      description: "List wireless point-to-point links"
      params:
        status: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_wireless_link:
      method: GET
      path: /wireless/wireless-links/{id}/
      access: read
      description: "Get a specific wireless link"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_wireless_link:
      method: POST
      path: /wireless/wireless-links/
      access: write
      description: "Create a wireless point-to-point link"
      params:
        interface_a: { type: integer, in: body, required: true }
        interface_b: { type: integer, in: body, required: true }
        ssid: { type: string, in: body }
        status: { type: string, in: body, description: "connected, planned, decommissioning" }
        auth_type: { type: string, in: body }
        auth_cipher: { type: string, in: body }
        auth_psk: { type: string, in: body }
        distance: { type: number, in: body }
        distance_unit: { type: string, in: body, description: "km, m, mi, ft" }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_wireless_link:
      method: PATCH
      path: /wireless/wireless-links/{id}/
      access: write
      description: "Update a wireless link"
      params:
        id: { type: integer, in: path, required: true }
        ssid: { type: string, in: body }
        status: { type: string, in: body }
        auth_type: { type: string, in: body }
        auth_cipher: { type: string, in: body }
        auth_psk: { type: string, in: body }
        distance: { type: number, in: body }
        distance_unit: { type: string, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_wireless_link:
      method: DELETE
      path: /wireless/wireless-links/{id}/
      access: dangerous
      description: "Delete a wireless link"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # VPN -- Tunnels & Tunnel Groups
    # =========================================================================

    list_tunnel_groups:
      method: GET
      path: /vpn/tunnel-groups/
      access: read
      description: "List tunnel groups (logical grouping of VPN tunnels)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_tunnel_group:
      method: GET
      path: /vpn/tunnel-groups/{id}/
      access: read
      description: "Get a specific tunnel group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_tunnel_group:
      method: POST
      path: /vpn/tunnel-groups/
      access: write
      description: "Create a tunnel group"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_tunnel_group:
      method: PATCH
      path: /vpn/tunnel-groups/{id}/
      access: write
      description: "Update a tunnel group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_tunnel_group:
      method: DELETE
      path: /vpn/tunnel-groups/{id}/
      access: dangerous
      description: "Delete a tunnel group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_tunnels:
      method: GET
      path: /vpn/tunnels/
      access: read
      description: "List VPN tunnels"
      params:
        name: { type: string, in: query }
        status: { type: string, in: query, description: "planned, active, disabled" }
        group: { type: string, in: query }
        group_id: { type: integer, in: query }
        encapsulation: { type: string, in: query }
        ipsec_profile: { type: string, in: query }
        ipsec_profile_id: { type: integer, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_tunnel:
      method: GET
      path: /vpn/tunnels/{id}/
      access: read
      description: "Get a specific tunnel"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_tunnel:
      method: POST
      path: /vpn/tunnels/
      access: write
      description: "Create a VPN tunnel"
      params:
        name: { type: string, in: body, required: true }
        status: { type: string, in: body, description: "planned, active, disabled" }
        group: { type: integer, in: body }
        encapsulation: { type: string, in: body, required: true, description: "ipsec-transport, ipsec-tunnel, ip-ip, gre, wireguard, openvpn, l2tp, pptp" }
        ipsec_profile: { type: integer, in: body }
        tenant: { type: integer, in: body }
        tunnel_id: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_tunnel:
      method: PATCH
      path: /vpn/tunnels/{id}/
      access: write
      description: "Update a tunnel"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        status: { type: string, in: body }
        group: { type: integer, in: body }
        encapsulation: { type: string, in: body }
        ipsec_profile: { type: integer, in: body }
        tenant: { type: integer, in: body }
        tunnel_id: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_tunnel:
      method: DELETE
      path: /vpn/tunnels/{id}/
      access: dangerous
      description: "Delete a tunnel"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_tunnel_terminations:
      method: GET
      path: /vpn/tunnel-terminations/
      access: read
      description: "List tunnel terminations (per-side endpoints of a VPN tunnel)"
      params:
        tunnel: { type: integer, in: query }
        tunnel_id: { type: integer, in: query }
        role: { type: string, in: query, description: "peer, hub, spoke" }
        termination_type: { type: string, in: query, description: "dcim.interface, virtualization.vminterface" }
        termination_id: { type: integer, in: query }
        outside_ip: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_tunnel_termination:
      method: GET
      path: /vpn/tunnel-terminations/{id}/
      access: read
      description: "Get a specific tunnel termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_tunnel_termination:
      method: POST
      path: /vpn/tunnel-terminations/
      access: write
      description: "Add a termination to a VPN tunnel"
      params:
        tunnel: { type: integer, in: body, required: true }
        role: { type: string, in: body, required: true, description: "peer, hub, spoke" }
        termination_type: { type: string, in: body, required: true, description: "dcim.interface or virtualization.vminterface" }
        termination_id: { type: integer, in: body, required: true }
        outside_ip: { type: integer, in: body, description: "Outside (public) IP address ID" }
        tags: { type: array, in: body }
      pagination: none

    update_tunnel_termination:
      method: PATCH
      path: /vpn/tunnel-terminations/{id}/
      access: write
      description: "Update a tunnel termination"
      params:
        id: { type: integer, in: path, required: true }
        role: { type: string, in: body }
        termination_type: { type: string, in: body }
        termination_id: { type: integer, in: body }
        outside_ip: { type: integer, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_tunnel_termination:
      method: DELETE
      path: /vpn/tunnel-terminations/{id}/
      access: dangerous
      description: "Delete a tunnel termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # VPN -- IKE & IPSec
    # =========================================================================

    list_ike_proposals:
      method: GET
      path: /vpn/ike-proposals/
      access: read
      description: "List IKE proposals (encryption/authentication algorithm bundles for IKE phase 1)"
      params:
        name: { type: string, in: query }
        authentication_method: { type: string, in: query }
        encryption_algorithm: { type: string, in: query }
        authentication_algorithm: { type: string, in: query }
        group: { type: integer, in: query, description: "DH group number" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_ike_proposal:
      method: GET
      path: /vpn/ike-proposals/{id}/
      access: read
      description: "Get a specific IKE proposal"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_ike_proposal:
      method: POST
      path: /vpn/ike-proposals/
      access: write
      description: "Create an IKE proposal"
      params:
        name: { type: string, in: body, required: true }
        authentication_method: { type: string, in: body, required: true, description: "preshared-keys, certificates, rsa-signatures, dsa-signatures" }
        encryption_algorithm: { type: string, in: body, required: true, description: "aes-128-cbc, aes-128-gcm, aes-192-cbc, aes-192-gcm, aes-256-cbc, aes-256-gcm, 3des, des" }
        authentication_algorithm: { type: string, in: body, required: true, description: "hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512, hmac-md5" }
        group: { type: integer, in: body, required: true, description: "DH group: 1,2,5,14,15,16,17,18,19,20,21,24" }
        sa_lifetime: { type: integer, in: body, description: "Security Association lifetime in seconds" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_ike_proposal:
      method: PATCH
      path: /vpn/ike-proposals/{id}/
      access: write
      description: "Update an IKE proposal"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        authentication_method: { type: string, in: body }
        encryption_algorithm: { type: string, in: body }
        authentication_algorithm: { type: string, in: body }
        group: { type: integer, in: body }
        sa_lifetime: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_ike_proposal:
      method: DELETE
      path: /vpn/ike-proposals/{id}/
      access: dangerous
      description: "Delete an IKE proposal"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_ike_policies:
      method: GET
      path: /vpn/ike-policies/
      access: read
      description: "List IKE policies (named groups of proposals + version + mode)"
      params:
        name: { type: string, in: query }
        version: { type: integer, in: query, description: "1 or 2" }
        mode: { type: string, in: query, description: "aggressive, main" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_ike_policy:
      method: GET
      path: /vpn/ike-policies/{id}/
      access: read
      description: "Get a specific IKE policy"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_ike_policy:
      method: POST
      path: /vpn/ike-policies/
      access: write
      description: "Create an IKE policy"
      params:
        name: { type: string, in: body, required: true }
        version: { type: integer, in: body, required: true, description: "1 or 2" }
        mode: { type: string, in: body, description: "aggressive, main (required for v1)" }
        proposals: { type: array, in: body, required: true, description: "Array of IKE proposal IDs" }
        preshared_key: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_ike_policy:
      method: PATCH
      path: /vpn/ike-policies/{id}/
      access: write
      description: "Update an IKE policy"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        version: { type: integer, in: body }
        mode: { type: string, in: body }
        proposals: { type: array, in: body }
        preshared_key: { type: string, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_ike_policy:
      method: DELETE
      path: /vpn/ike-policies/{id}/
      access: dangerous
      description: "Delete an IKE policy"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_ipsec_proposals:
      method: GET
      path: /vpn/ipsec-proposals/
      access: read
      description: "List IPSec proposals (encryption/auth bundles for IPSec phase 2)"
      params:
        name: { type: string, in: query }
        encryption_algorithm: { type: string, in: query }
        authentication_algorithm: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_ipsec_proposal:
      method: GET
      path: /vpn/ipsec-proposals/{id}/
      access: read
      description: "Get a specific IPSec proposal"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_ipsec_proposal:
      method: POST
      path: /vpn/ipsec-proposals/
      access: write
      description: "Create an IPSec proposal"
      params:
        name: { type: string, in: body, required: true }
        encryption_algorithm: { type: string, in: body, description: "aes-128-cbc, aes-128-gcm, aes-192-cbc, aes-192-gcm, aes-256-cbc, aes-256-gcm, 3des, des" }
        authentication_algorithm: { type: string, in: body, description: "hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512, hmac-md5" }
        sa_lifetime_seconds: { type: integer, in: body }
        sa_lifetime_data: { type: integer, in: body, description: "SA lifetime in kilobytes" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_ipsec_proposal:
      method: PATCH
      path: /vpn/ipsec-proposals/{id}/
      access: write
      description: "Update an IPSec proposal"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        encryption_algorithm: { type: string, in: body }
        authentication_algorithm: { type: string, in: body }
        sa_lifetime_seconds: { type: integer, in: body }
        sa_lifetime_data: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_ipsec_proposal:
      method: DELETE
      path: /vpn/ipsec-proposals/{id}/
      access: dangerous
      description: "Delete an IPSec proposal"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_ipsec_policies:
      method: GET
      path: /vpn/ipsec-policies/
      access: read
      description: "List IPSec policies (named bundles of IPSec proposals + PFS group)"
      params:
        name: { type: string, in: query }
        pfs_group: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_ipsec_policy:
      method: GET
      path: /vpn/ipsec-policies/{id}/
      access: read
      description: "Get a specific IPSec policy"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_ipsec_policy:
      method: POST
      path: /vpn/ipsec-policies/
      access: write
      description: "Create an IPSec policy"
      params:
        name: { type: string, in: body, required: true }
        proposals: { type: array, in: body, required: true, description: "Array of IPSec proposal IDs" }
        pfs_group: { type: integer, in: body, description: "Perfect Forward Secrecy DH group" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_ipsec_policy:
      method: PATCH
      path: /vpn/ipsec-policies/{id}/
      access: write
      description: "Update an IPSec policy"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        proposals: { type: array, in: body }
        pfs_group: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_ipsec_policy:
      method: DELETE
      path: /vpn/ipsec-policies/{id}/
      access: dangerous
      description: "Delete an IPSec policy"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_ipsec_profiles:
      method: GET
      path: /vpn/ipsec-profiles/
      access: read
      description: "List IPSec profiles (combination of IKE policy + IPSec policy + mode -- attach to a tunnel)"
      params:
        name: { type: string, in: query }
        mode: { type: string, in: query, description: "esp, ah" }
        ike_policy: { type: integer, in: query }
        ipsec_policy: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_ipsec_profile:
      method: GET
      path: /vpn/ipsec-profiles/{id}/
      access: read
      description: "Get a specific IPSec profile"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_ipsec_profile:
      method: POST
      path: /vpn/ipsec-profiles/
      access: write
      description: "Create an IPSec profile"
      params:
        name: { type: string, in: body, required: true }
        mode: { type: string, in: body, required: true, description: "esp or ah" }
        ike_policy: { type: integer, in: body, required: true }
        ipsec_policy: { type: integer, in: body, required: true }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_ipsec_profile:
      method: PATCH
      path: /vpn/ipsec-profiles/{id}/
      access: write
      description: "Update an IPSec profile"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        mode: { type: string, in: body }
        ike_policy: { type: integer, in: body }
        ipsec_policy: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_ipsec_profile:
      method: DELETE
      path: /vpn/ipsec-profiles/{id}/
      access: dangerous
      description: "Delete an IPSec profile"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # VPN -- L2VPN
    # =========================================================================

    list_l2vpns:
      method: GET
      path: /vpn/l2vpns/
      access: read
      description: "List L2VPN instances (VPLS, VXLAN, EVPN, etc.)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        type: { type: string, in: query }
        identifier: { type: integer, in: query }
        tenant: { type: string, in: query }
        tag: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_l2vpn:
      method: GET
      path: /vpn/l2vpns/{id}/
      access: read
      description: "Get a specific L2VPN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_l2vpn:
      method: POST
      path: /vpn/l2vpns/
      access: write
      description: "Create an L2VPN instance"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true, description: "vpws, vpls, vxlan, vxlan-evpn, mpls-evpn, pbb-evpn, epl, evpl, ep-lan, evp-lan, ep-tree, evp-tree" }
        identifier: { type: integer, in: body }
        import_targets: { type: array, in: body, description: "Array of route-target IDs" }
        export_targets: { type: array, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_l2vpn:
      method: PATCH
      path: /vpn/l2vpns/{id}/
      access: write
      description: "Update an L2VPN"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        type: { type: string, in: body }
        identifier: { type: integer, in: body }
        import_targets: { type: array, in: body }
        export_targets: { type: array, in: body }
        tenant: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_l2vpn:
      method: DELETE
      path: /vpn/l2vpns/{id}/
      access: dangerous
      description: "Delete an L2VPN"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_l2vpn_terminations:
      method: GET
      path: /vpn/l2vpn-terminations/
      access: read
      description: "List L2VPN terminations (attachments of VLANs/interfaces/VRFs to an L2VPN)"
      params:
        l2vpn: { type: integer, in: query }
        l2vpn_id: { type: integer, in: query }
        assigned_object_type: { type: string, in: query }
        assigned_object_id: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_l2vpn_termination:
      method: GET
      path: /vpn/l2vpn-terminations/{id}/
      access: read
      description: "Get a specific L2VPN termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_l2vpn_termination:
      method: POST
      path: /vpn/l2vpn-terminations/
      access: write
      description: "Attach an interface, VLAN, or VRF to an L2VPN"
      params:
        l2vpn: { type: integer, in: body, required: true }
        assigned_object_type: { type: string, in: body, required: true, description: "ipam.vlan, dcim.interface, virtualization.vminterface, ipam.vrf" }
        assigned_object_id: { type: integer, in: body, required: true }
        tags: { type: array, in: body }
      pagination: none

    update_l2vpn_termination:
      method: PATCH
      path: /vpn/l2vpn-terminations/{id}/
      access: write
      description: "Update an L2VPN termination"
      params:
        id: { type: integer, in: path, required: true }
        assigned_object_type: { type: string, in: body }
        assigned_object_id: { type: integer, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_l2vpn_termination:
      method: DELETE
      path: /vpn/l2vpn-terminations/{id}/
      access: dangerous
      description: "Delete an L2VPN termination"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # EXTRAS -- Tags, Journal, Config Contexts
    # =========================================================================

    list_tags:
      method: GET
      path: /extras/tags/
      access: read
      description: "List all tags"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_tag:
      method: POST
      path: /extras/tags/
      access: write
      description: "Create a tag"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        color: { type: string, in: body, description: "6-char hex color (e.g. aa1409)" }
        description: { type: string, in: body }
      pagination: none

    get_tag:
      method: GET
      path: /extras/tags/{id}/
      access: read
      description: "Get a specific tag"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_tag:
      method: PATCH
      path: /extras/tags/{id}/
      access: write
      description: "Update a tag"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        color: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_tag:
      method: DELETE
      path: /extras/tags/{id}/
      access: dangerous
      description: "Delete a tag"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # EXTRAS -- Custom Fields
    # =========================================================================

    list_custom_fields:
      method: GET
      path: /extras/custom-fields/
      access: read
      description: "List all custom field definitions"
      params:
        name: { type: string, in: query }
        content_types: { type: string, in: query, description: "Filter by content type (e.g. dcim.device)" }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_custom_field:
      method: GET
      path: /extras/custom-fields/{id}/
      access: read
      description: "Get a specific custom field definition"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_custom_field:
      method: POST
      path: /extras/custom-fields/
      access: admin
      description: "Create a custom field definition. Assign to object types via object_types array."
      params:
        name: { type: string, in: body, required: true, description: "Internal field name (snake_case)" }
        label: { type: string, in: body, description: "Human-readable label" }
        type: { type: string, in: body, required: true, description: "text, longtext, integer, decimal, boolean, date, datetime, url, json, select, multiselect, object, multiobject" }
        object_types: { type: array, in: body, required: true, description: "Content types: ['dcim.device', 'virtualization.virtualmachine', etc.]" }
        group_name: { type: string, in: body, description: "Group label for UI grouping" }
        description: { type: string, in: body }
        required: { type: boolean, in: body }
        search_weight: { type: integer, in: body, description: "Search weight (0=disabled, 1000=default, higher=more weight)" }
        filter_logic: { type: string, in: body, description: "disabled, loose, exact" }
        ui_visible: { type: string, in: body, description: "always, if-set, hidden" }
        ui_editable: { type: string, in: body, description: "yes, no, hidden" }
        weight: { type: integer, in: body, description: "Display order (lower=first)" }
        default: { type: string, in: body, description: "Default value" }
        choice_set: { type: integer, in: body, description: "ID of a custom field choice set (for select/multiselect)" }
        validation_minimum: { type: integer, in: body }
        validation_maximum: { type: integer, in: body }
        validation_regex: { type: string, in: body }
      pagination: none

    update_custom_field:
      method: PATCH
      path: /extras/custom-fields/{id}/
      access: admin
      description: "Update a custom field definition"
      params:
        id: { type: integer, in: path, required: true }
        label: { type: string, in: body }
        description: { type: string, in: body }
        required: { type: boolean, in: body }
        ui_visible: { type: string, in: body }
        ui_editable: { type: string, in: body }
        weight: { type: integer, in: body }
        default: { type: string, in: body }
        object_types: { type: array, in: body }
      pagination: none

    delete_custom_field:
      method: DELETE
      path: /extras/custom-fields/{id}/
      access: dangerous
      description: "Delete a custom field definition. WARNING: deletes all stored values."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # EXTRAS -- Custom Field Choice Sets
    # =========================================================================

    list_custom_field_choice_sets:
      method: GET
      path: /extras/custom-field-choice-sets/
      access: read
      description: "List all custom field choice sets"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_custom_field_choice_set:
      method: GET
      path: /extras/custom-field-choice-sets/{id}/
      access: read
      description: "Get a specific custom field choice set"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_custom_field_choice_set:
      method: POST
      path: /extras/custom-field-choice-sets/
      access: admin
      description: "Create a custom field choice set for select/multiselect custom fields"
      params:
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        base_choices: { type: string, in: body, description: "Optional base choice set to extend (e.g. 'IATA')" }
        extra_choices: { type: array, in: body, required: true, description: "Array of [value, label] pairs, e.g. [['a','Alpha'],['b','Beta']]" }
        order_alphabetically: { type: boolean, in: body, description: "Sort choices alphabetically (default: false)" }
      pagination: none

    update_custom_field_choice_set:
      method: PATCH
      path: /extras/custom-field-choice-sets/{id}/
      access: admin
      description: "Update a custom field choice set"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        description: { type: string, in: body }
        extra_choices: { type: array, in: body, description: "Array of [value, label] pairs" }
        order_alphabetically: { type: boolean, in: body }
      pagination: none

    delete_custom_field_choice_set:
      method: DELETE
      path: /extras/custom-field-choice-sets/{id}/
      access: dangerous
      description: "Delete a custom field choice set. WARNING: breaks any custom fields referencing this set."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_object_changes:
      method: GET
      path: /core/object-changes/
      access: read
      description: "List the change log — every create/update/delete on any NetBox object is recorded with timestamp, user, action, and pre/post-change snapshots. Use to audit who changed what and when."
      params:
        user_id: { type: integer, in: query, description: "Filter by user ID who made the change" }
        user_name: { type: string, in: query, description: "Filter by username" }
        action: { type: string, in: query, description: "create, update, or delete" }
        changed_object_type: { type: string, in: query, description: "Content type, e.g. ipam.service, dcim.device, virtualization.virtualmachine" }
        changed_object_id: { type: integer, in: query, description: "Filter by the changed object's ID" }
        request_id: { type: string, in: query, description: "Filter by request UUID (groups changes from one API call)" }
        time_before: { type: string, in: query, description: "ISO 8601 timestamp upper bound" }
        time_after: { type: string, in: query, description: "ISO 8601 timestamp lower bound" }
        q: { type: string, in: query, description: "Search object representation" }
        ordering: { type: string, in: query, description: "e.g. -time (newest first)" }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    list_journal_entries:
      method: GET
      path: /extras/journal-entries/
      access: read
      description: "List journal entries (change notes on objects)"
      params:
        assigned_object_type: { type: string, in: query }
        assigned_object_id: { type: integer, in: query }
        kind: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_journal_entry:
      method: POST
      path: /extras/journal-entries/
      access: write
      description: "Create a journal entry on an object"
      params:
        assigned_object_type: { type: string, in: body, required: true }
        assigned_object_id: { type: integer, in: body, required: true }
        kind: { type: string, in: body, description: "info, success, warning, danger" }
        comments: { type: string, in: body, required: true }
        tags: { type: array, in: body }
      pagination: none

    list_config_contexts:
      method: GET
      path: /extras/config-contexts/
      access: read
      description: "List configuration contexts (rendered config data for devices/VMs)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    create_config_context:
      method: POST
      path: /extras/config-contexts/
      access: write
      description: "Create a configuration context"
      params:
        name: { type: string, in: body, required: true }
        data: { type: object, in: body, required: true, description: "JSON config data" }
        weight: { type: integer, in: body }
        is_active: { type: boolean, in: body }
        regions: { type: array, in: body, description: "Array of region IDs" }
        site_groups: { type: array, in: body }
        sites: { type: array, in: body, description: "Array of site IDs" }
        locations: { type: array, in: body }
        device_types: { type: array, in: body }
        roles: { type: array, in: body, description: "Array of role IDs" }
        platforms: { type: array, in: body, description: "Array of platform IDs" }
        cluster_types: { type: array, in: body }
        cluster_groups: { type: array, in: body }
        clusters: { type: array, in: body }
        tenant_groups: { type: array, in: body }
        tenants: { type: array, in: body }
        tags: { type: array, in: body }
        description: { type: string, in: body }
      pagination: none

    get_config_context:
      method: GET
      path: /extras/config-contexts/{id}/
      access: read
      description: "Get a specific config context"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_config_context:
      method: PATCH
      path: /extras/config-contexts/{id}/
      access: write
      description: "Update a config context"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        data: { type: object, in: body }
        weight: { type: integer, in: body }
        is_active: { type: boolean, in: body }
        regions: { type: array, in: body }
        site_groups: { type: array, in: body }
        sites: { type: array, in: body }
        locations: { type: array, in: body }
        device_types: { type: array, in: body }
        roles: { type: array, in: body }
        platforms: { type: array, in: body }
        cluster_types: { type: array, in: body }
        cluster_groups: { type: array, in: body }
        clusters: { type: array, in: body }
        tenant_groups: { type: array, in: body }
        tenants: { type: array, in: body }
        tags: { type: array, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_config_context:
      method: DELETE
      path: /extras/config-contexts/{id}/
      access: dangerous
      description: "Delete a config context"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_journal_entry:
      method: GET
      path: /extras/journal-entries/{id}/
      access: read
      description: "Get a specific journal entry"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    update_journal_entry:
      method: PATCH
      path: /extras/journal-entries/{id}/
      access: write
      description: "Update a journal entry"
      params:
        id: { type: integer, in: path, required: true }
        kind: { type: string, in: body, description: "info, success, warning, danger" }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_journal_entry:
      method: DELETE
      path: /extras/journal-entries/{id}/
      access: dangerous
      description: "Delete a journal entry"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # EXTRAS -- Config Templates
    # =========================================================================

    list_config_templates:
      method: GET
      path: /extras/config-templates/
      access: read
      description: "List config templates (Jinja2 templates rendered against config-context data)"
      params:
        name: { type: string, in: query }
        data_source: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_config_template:
      method: GET
      path: /extras/config-templates/{id}/
      access: read
      description: "Get a specific config template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_config_template:
      method: POST
      path: /extras/config-templates/
      access: write
      description: "Create a config template"
      params:
        name: { type: string, in: body, required: true }
        template_code: { type: string, in: body, description: "Jinja2 template source -- omit if using data_source" }
        environment_params: { type: object, in: body, description: "Extra params passed to Jinja2 environment" }
        data_source: { type: integer, in: body, description: "Sync template from a core data source" }
        data_file: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_config_template:
      method: PATCH
      path: /extras/config-templates/{id}/
      access: write
      description: "Update a config template"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        template_code: { type: string, in: body }
        environment_params: { type: object, in: body }
        data_source: { type: integer, in: body }
        data_file: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_config_template:
      method: DELETE
      path: /extras/config-templates/{id}/
      access: dangerous
      description: "Delete a config template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    render_config_template:
      method: POST
      path: /extras/config-templates/{id}/render/
      access: read
      description: "Render a config template with the supplied context. Returns text/plain or JSON."
      params:
        id: { type: integer, in: path, required: true }
        context: { type: object, in: body, description: "Override context variables (merged with config-context)" }
      pagination: none

    # =========================================================================
    # EXTRAS -- Webhooks & Event Rules
    # =========================================================================

    list_webhooks:
      method: GET
      path: /extras/webhooks/
      access: read
      description: "List webhooks (HTTP callbacks that fire on object events)"
      params:
        name: { type: string, in: query }
        payload_url: { type: string, in: query }
        http_method: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_webhook:
      method: GET
      path: /extras/webhooks/{id}/
      access: read
      description: "Get a specific webhook"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_webhook:
      method: POST
      path: /extras/webhooks/
      access: admin
      description: "Create a webhook. Webhooks are now decoupled from triggers -- use event-rules to bind a webhook to a model + event."
      params:
        name: { type: string, in: body, required: true }
        payload_url: { type: string, in: body, required: true }
        http_method: { type: string, in: body, description: "GET, POST, PUT, PATCH, DELETE" }
        http_content_type: { type: string, in: body, default: "application/json" }
        additional_headers: { type: string, in: body, description: "Extra HTTP headers as plain text 'Key: Value' per line" }
        body_template: { type: string, in: body, description: "Jinja2 template for the request body. Omit to send default JSON." }
        secret: { type: string, in: body, description: "HMAC secret for X-Hook-Signature header" }
        ssl_verification: { type: boolean, in: body, default: true }
        ca_file_path: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_webhook:
      method: PATCH
      path: /extras/webhooks/{id}/
      access: admin
      description: "Update a webhook"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        payload_url: { type: string, in: body }
        http_method: { type: string, in: body }
        http_content_type: { type: string, in: body }
        additional_headers: { type: string, in: body }
        body_template: { type: string, in: body }
        secret: { type: string, in: body }
        ssl_verification: { type: boolean, in: body }
        ca_file_path: { type: string, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_webhook:
      method: DELETE
      path: /extras/webhooks/{id}/
      access: dangerous
      description: "Delete a webhook"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_event_rules:
      method: GET
      path: /extras/event-rules/
      access: read
      description: "List event rules (binding: model + event type -> action target like webhook or script)"
      params:
        name: { type: string, in: query }
        enabled: { type: boolean, in: query }
        action_type: { type: string, in: query, description: "webhook, script, notification-group" }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_event_rule:
      method: GET
      path: /extras/event-rules/{id}/
      access: read
      description: "Get a specific event rule"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_event_rule:
      method: POST
      path: /extras/event-rules/
      access: admin
      description: "Create an event rule"
      params:
        name: { type: string, in: body, required: true }
        object_types: { type: array, in: body, required: true, description: "Array of content types, e.g. ['dcim.device']" }
        enabled: { type: boolean, in: body, default: true }
        event_types: { type: array, in: body, required: true, description: "Array of event types: object_created, object_updated, object_deleted, job_started, job_completed, job_failed, job_errored" }
        conditions: { type: object, in: body, description: "Optional JSON condition expression for filtering" }
        action_type: { type: string, in: body, required: true, description: "webhook, script, notification-group" }
        action_object_type: { type: string, in: body, description: "ContentType of action target, e.g. extras.webhook" }
        action_object_id: { type: integer, in: body, required: true }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_event_rule:
      method: PATCH
      path: /extras/event-rules/{id}/
      access: admin
      description: "Update an event rule"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        object_types: { type: array, in: body }
        enabled: { type: boolean, in: body }
        event_types: { type: array, in: body }
        conditions: { type: object, in: body }
        action_type: { type: string, in: body }
        action_object_type: { type: string, in: body }
        action_object_id: { type: integer, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_event_rule:
      method: DELETE
      path: /extras/event-rules/{id}/
      access: dangerous
      description: "Delete an event rule"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # EXTRAS -- Scripts, Export Templates, Saved Filters, Custom Links
    # =========================================================================

    list_scripts:
      method: GET
      path: /extras/scripts/
      access: read
      description: >
        List installed custom scripts. NetBox 4.0+ merged reports into scripts.
        Each script has a module + name and is identified by id (or 'module.ClassName' string).
      params:
        name: { type: string, in: query }
        module: { type: string, in: query }
        is_executable: { type: boolean, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_script:
      method: GET
      path: /extras/scripts/{id}/
      access: read
      description: "Get script details (parameters schema, module info)"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    run_script:
      method: POST
      path: /extras/scripts/{id}/
      access: admin
      description: >
        Execute a custom script. Returns a job ID; poll /core/jobs/{job_id}/ for status.
        Data must match the script's declared parameters.
      params:
        id: { type: integer, in: path, required: true }
        data: { type: object, in: body, required: true, description: "Script parameter values" }
        commit: { type: boolean, in: body, default: true, description: "Whether to commit DB changes (true) or dry-run (false)" }
        schedule_at: { type: string, in: body, description: "ISO datetime to defer execution" }
        interval: { type: integer, in: body, description: "Run every N minutes (recurring)" }
      pagination: none

    list_export_templates:
      method: GET
      path: /extras/export-templates/
      access: read
      description: "List export templates (Jinja2 templates that render lists of objects to CSV/JSON/text)"
      params:
        name: { type: string, in: query }
        object_types: { type: string, in: query }
        mime_type: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_export_template:
      method: GET
      path: /extras/export-templates/{id}/
      access: read
      description: "Get a specific export template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_export_template:
      method: POST
      path: /extras/export-templates/
      access: admin
      description: "Create an export template"
      params:
        name: { type: string, in: body, required: true }
        object_types: { type: array, in: body, required: true, description: "ContentTypes this template applies to" }
        template_code: { type: string, in: body, description: "Jinja2 template source" }
        mime_type: { type: string, in: body, description: "Output MIME type, e.g. text/csv" }
        file_extension: { type: string, in: body }
        as_attachment: { type: boolean, in: body, default: true }
        data_source: { type: integer, in: body }
        data_file: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_export_template:
      method: PATCH
      path: /extras/export-templates/{id}/
      access: admin
      description: "Update an export template"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        object_types: { type: array, in: body }
        template_code: { type: string, in: body }
        mime_type: { type: string, in: body }
        file_extension: { type: string, in: body }
        as_attachment: { type: boolean, in: body }
        data_source: { type: integer, in: body }
        data_file: { type: integer, in: body }
        description: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_export_template:
      method: DELETE
      path: /extras/export-templates/{id}/
      access: dangerous
      description: "Delete an export template"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_saved_filters:
      method: GET
      path: /extras/saved-filters/
      access: read
      description: "List saved filters (reusable URL query parameter sets per object type)"
      params:
        name: { type: string, in: query }
        slug: { type: string, in: query }
        object_types: { type: string, in: query }
        enabled: { type: boolean, in: query }
        shared: { type: boolean, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_saved_filter:
      method: GET
      path: /extras/saved-filters/{id}/
      access: read
      description: "Get a specific saved filter"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_saved_filter:
      method: POST
      path: /extras/saved-filters/
      access: write
      description: "Create a saved filter"
      params:
        name: { type: string, in: body, required: true }
        slug: { type: string, in: body, required: true }
        object_types: { type: array, in: body, required: true }
        parameters: { type: object, in: body, required: true, description: "URL query parameter dictionary" }
        weight: { type: integer, in: body }
        enabled: { type: boolean, in: body, default: true }
        shared: { type: boolean, in: body, default: true }
        user: { type: integer, in: body }
        description: { type: string, in: body }
      pagination: none

    update_saved_filter:
      method: PATCH
      path: /extras/saved-filters/{id}/
      access: write
      description: "Update a saved filter"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        slug: { type: string, in: body }
        object_types: { type: array, in: body }
        parameters: { type: object, in: body }
        weight: { type: integer, in: body }
        enabled: { type: boolean, in: body }
        shared: { type: boolean, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_saved_filter:
      method: DELETE
      path: /extras/saved-filters/{id}/
      access: dangerous
      description: "Delete a saved filter"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_custom_links:
      method: GET
      path: /extras/custom-links/
      access: read
      description: "List custom links (extra UI buttons shown on object pages)"
      params:
        name: { type: string, in: query }
        object_types: { type: string, in: query }
        enabled: { type: boolean, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_custom_link:
      method: GET
      path: /extras/custom-links/{id}/
      access: read
      description: "Get a specific custom link"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_custom_link:
      method: POST
      path: /extras/custom-links/
      access: admin
      description: "Create a custom link"
      params:
        name: { type: string, in: body, required: true }
        object_types: { type: array, in: body, required: true }
        link_text: { type: string, in: body, required: true, description: "Jinja2 template for link text" }
        link_url: { type: string, in: body, required: true, description: "Jinja2 template for URL" }
        weight: { type: integer, in: body }
        group_name: { type: string, in: body, description: "Optional grouping label" }
        button_class: { type: string, in: body, description: "default, outline-secondary, outline-primary, outline-success, etc." }
        new_window: { type: boolean, in: body }
        enabled: { type: boolean, in: body, default: true }
      pagination: none

    update_custom_link:
      method: PATCH
      path: /extras/custom-links/{id}/
      access: admin
      description: "Update a custom link"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        object_types: { type: array, in: body }
        link_text: { type: string, in: body }
        link_url: { type: string, in: body }
        weight: { type: integer, in: body }
        group_name: { type: string, in: body }
        button_class: { type: string, in: body }
        new_window: { type: boolean, in: body }
        enabled: { type: boolean, in: body }
      pagination: none

    delete_custom_link:
      method: DELETE
      path: /extras/custom-links/{id}/
      access: dangerous
      description: "Delete a custom link"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    # =========================================================================
    # EXTRAS -- Bookmarks, Notifications, Images
    # =========================================================================

    list_bookmarks:
      method: GET
      path: /extras/bookmarks/
      access: read
      description: "List bookmarks (user-specific bookmarks of NetBox objects)"
      params:
        user: { type: integer, in: query }
        user_id: { type: integer, in: query }
        object_type: { type: string, in: query }
        object_id: { type: integer, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_bookmark:
      method: GET
      path: /extras/bookmarks/{id}/
      access: read
      description: "Get a specific bookmark"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_bookmark:
      method: POST
      path: /extras/bookmarks/
      access: write
      description: "Create a bookmark"
      params:
        object_type: { type: string, in: body, required: true, description: "ContentType label, e.g. 'dcim.device'" }
        object_id: { type: integer, in: body, required: true }
        user: { type: integer, in: body, required: true }
      pagination: none

    delete_bookmark:
      method: DELETE
      path: /extras/bookmarks/{id}/
      access: dangerous
      description: "Delete a bookmark"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_notifications:
      method: GET
      path: /extras/notifications/
      access: read
      description: "List notifications (in-app messages for users, NetBox 4.1+)"
      params:
        user: { type: integer, in: query }
        user_id: { type: integer, in: query }
        read: { type: string, in: query, description: "ISO datetime; null for unread" }
        event_type: { type: string, in: query }
        object_type: { type: string, in: query }
        object_id: { type: integer, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_notification:
      method: GET
      path: /extras/notifications/{id}/
      access: read
      description: "Get a specific notification"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_notification:
      method: POST
      path: /extras/notifications/
      access: write
      description: "Create a notification (typically used by automation, not humans)"
      params:
        user: { type: integer, in: body, required: true }
        object_type: { type: string, in: body, required: true }
        object_id: { type: integer, in: body, required: true }
        event_type: { type: string, in: body, required: true }
      pagination: none

    update_notification:
      method: PATCH
      path: /extras/notifications/{id}/
      access: write
      description: "Mark notification as read by setting 'read' to a datetime"
      params:
        id: { type: integer, in: path, required: true }
        read: { type: string, in: body, description: "ISO datetime when the notification was read" }
      pagination: none

    delete_notification:
      method: DELETE
      path: /extras/notifications/{id}/
      access: dangerous
      description: "Delete a notification"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_notification_groups:
      method: GET
      path: /extras/notification-groups/
      access: read
      description: "List notification groups (sets of users + groups that receive event-rule notifications)"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_notification_group:
      method: GET
      path: /extras/notification-groups/{id}/
      access: read
      description: "Get a specific notification group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_notification_group:
      method: POST
      path: /extras/notification-groups/
      access: admin
      description: "Create a notification group"
      params:
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        users: { type: array, in: body, description: "Array of user IDs" }
        groups: { type: array, in: body, description: "Array of group IDs" }
      pagination: none

    update_notification_group:
      method: PATCH
      path: /extras/notification-groups/{id}/
      access: admin
      description: "Update a notification group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        description: { type: string, in: body }
        users: { type: array, in: body }
        groups: { type: array, in: body }
      pagination: none

    delete_notification_group:
      method: DELETE
      path: /extras/notification-groups/{id}/
      access: dangerous
      description: "Delete a notification group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_subscriptions:
      method: GET
      path: /extras/subscriptions/
      access: read
      description: "List subscriptions (per-user follow lists for specific objects)"
      params:
        user: { type: integer, in: query }
        user_id: { type: integer, in: query }
        object_type: { type: string, in: query }
        object_id: { type: integer, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_subscription:
      method: GET
      path: /extras/subscriptions/{id}/
      access: read
      description: "Get a specific subscription"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_subscription:
      method: POST
      path: /extras/subscriptions/
      access: write
      description: "Subscribe a user to events on an object"
      params:
        user: { type: integer, in: body, required: true }
        object_type: { type: string, in: body, required: true }
        object_id: { type: integer, in: body, required: true }
      pagination: none

    delete_subscription:
      method: DELETE
      path: /extras/subscriptions/{id}/
      access: dangerous
      description: "Delete a subscription"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_image_attachments:
      method: GET
      path: /extras/image-attachments/
      access: read
      description: "List image attachments (rack diagrams, photos, etc. attached to NetBox objects)"
      params:
        object_type: { type: string, in: query }
        object_id: { type: integer, in: query }
        name: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_image_attachment:
      method: GET
      path: /extras/image-attachments/{id}/
      access: read
      description: "Get a specific image attachment"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_image_attachment:
      method: POST
      path: /extras/image-attachments/
      access: write
      content_type: multipart/form-data
      description: "Attach an image to an object. Uses multipart/form-data with the image bytes."
      params:
        object_type: { type: string, in: body, required: true, description: "e.g. dcim.device, dcim.site, dcim.rack" }
        object_id: { type: integer, in: body, required: true }
        name: { type: string, in: body }
        image: { type: file_url, in: body, required: true, description: "URL of the image to upload" }
      pagination: none

    update_image_attachment:
      method: PATCH
      path: /extras/image-attachments/{id}/
      access: write
      description: "Update image attachment metadata (name)"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
      pagination: none

    delete_image_attachment:
      method: DELETE
      path: /extras/image-attachments/{id}/
      access: dangerous
      description: "Delete an image attachment"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    get_dashboard:
      method: GET
      path: /extras/dashboard/
      access: read
      description: "Get the current user's dashboard configuration (singleton -- not a list endpoint)"
      params: {}
      pagination: none

    update_dashboard:
      method: PATCH
      path: /extras/dashboard/
      access: write
      description: "Update the current user's dashboard layout"
      params:
        layout: { type: array, in: body, description: "Array of widget definitions" }
        config: { type: object, in: body }
      pagination: none

    # =========================================================================
    # USERS -- Users, Groups, Permissions, Tokens
    # =========================================================================

    list_users:
      method: GET
      path: /users/users/
      access: admin
      description: "List NetBox users. Admin-only endpoint."
      params:
        username: { type: string, in: query }
        email: { type: string, in: query }
        first_name: { type: string, in: query }
        last_name: { type: string, in: query }
        is_active: { type: boolean, in: query }
        is_staff: { type: boolean, in: query }
        is_superuser: { type: boolean, in: query }
        group: { type: string, in: query }
        group_id: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_user:
      method: GET
      path: /users/users/{id}/
      access: admin
      description: "Get a specific user"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_user:
      method: POST
      path: /users/users/
      access: admin
      description: "Create a NetBox user"
      params:
        username: { type: string, in: body, required: true }
        password: { type: string, in: body, required: true }
        email: { type: string, in: body }
        first_name: { type: string, in: body }
        last_name: { type: string, in: body }
        is_active: { type: boolean, in: body, default: true }
        is_staff: { type: boolean, in: body }
        is_superuser: { type: boolean, in: body }
        groups: { type: array, in: body, description: "Array of group IDs" }
      pagination: none

    update_user:
      method: PATCH
      path: /users/users/{id}/
      access: admin
      description: "Update a user. Passing 'password' resets the password."
      params:
        id: { type: integer, in: path, required: true }
        username: { type: string, in: body }
        password: { type: string, in: body }
        email: { type: string, in: body }
        first_name: { type: string, in: body }
        last_name: { type: string, in: body }
        is_active: { type: boolean, in: body }
        is_staff: { type: boolean, in: body }
        is_superuser: { type: boolean, in: body }
        groups: { type: array, in: body }
      pagination: none

    delete_user:
      method: DELETE
      path: /users/users/{id}/
      access: dangerous
      description: "Delete a user"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_groups:
      method: GET
      path: /users/groups/
      access: admin
      description: "List user groups"
      params:
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_group:
      method: GET
      path: /users/groups/{id}/
      access: admin
      description: "Get a specific group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_group:
      method: POST
      path: /users/groups/
      access: admin
      description: "Create a user group"
      params:
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
      pagination: none

    update_group:
      method: PATCH
      path: /users/groups/{id}/
      access: admin
      description: "Update a group"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_group:
      method: DELETE
      path: /users/groups/{id}/
      access: dangerous
      description: "Delete a group"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_permissions:
      method: GET
      path: /users/permissions/
      access: admin
      description: "List object permissions (per-model + per-action grants assigned to users/groups)"
      params:
        name: { type: string, in: query }
        enabled: { type: boolean, in: query }
        object_types: { type: string, in: query }
        user: { type: integer, in: query }
        group: { type: integer, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_permission:
      method: GET
      path: /users/permissions/{id}/
      access: admin
      description: "Get a specific permission"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_permission:
      method: POST
      path: /users/permissions/
      access: admin
      description: "Create an object permission"
      params:
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        enabled: { type: boolean, in: body, default: true }
        object_types: { type: array, in: body, required: true }
        actions: { type: array, in: body, required: true, description: "Array of action names: view, add, change, delete (or custom action names)" }
        constraints: { type: object, in: body, description: "Optional ORM-style filter for restricting which objects this permission applies to" }
        users: { type: array, in: body }
        groups: { type: array, in: body }
      pagination: none

    update_permission:
      method: PATCH
      path: /users/permissions/{id}/
      access: admin
      description: "Update a permission"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        description: { type: string, in: body }
        enabled: { type: boolean, in: body }
        object_types: { type: array, in: body }
        actions: { type: array, in: body }
        constraints: { type: object, in: body }
        users: { type: array, in: body }
        groups: { type: array, in: body }
      pagination: none

    delete_permission:
      method: DELETE
      path: /users/permissions/{id}/
      access: dangerous
      description: "Delete a permission"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_tokens:
      method: GET
      path: /users/tokens/
      access: admin
      description: "List API tokens. Admin sees all; regular users see only their own."
      params:
        user: { type: string, in: query }
        user_id: { type: integer, in: query }
        key: { type: string, in: query }
        write_enabled: { type: boolean, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_token:
      method: GET
      path: /users/tokens/{id}/
      access: admin
      description: "Get a specific token (key shown only on create)"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_token:
      method: POST
      path: /users/tokens/
      access: admin
      description: "Issue a new API token for a user. The 'key' field in the response is shown only once."
      params:
        user: { type: integer, in: body, required: true }
        key: { type: string, in: body, description: "Specific token value (auto-generated if omitted)" }
        write_enabled: { type: boolean, in: body, default: true }
        expires: { type: string, in: body, description: "ISO datetime; omit for no expiry" }
        last_used: { type: string, in: body }
        allowed_ips: { type: array, in: body, description: "Array of CIDR strings; empty = unrestricted" }
        description: { type: string, in: body }
      pagination: none

    update_token:
      method: PATCH
      path: /users/tokens/{id}/
      access: admin
      description: "Update token metadata (description, expiry, allowed IPs)"
      params:
        id: { type: integer, in: path, required: true }
        write_enabled: { type: boolean, in: body }
        expires: { type: string, in: body }
        allowed_ips: { type: array, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_token:
      method: DELETE
      path: /users/tokens/{id}/
      access: dangerous
      description: "Revoke a token"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    provision_token:
      method: POST
      path: /users/tokens/provision/
      access: admin
      description: >
        Issue a token by username+password without an existing token.
        Bootstrap-only endpoint. Returns the new token in the response body.
      params:
        username: { type: string, in: body, required: true }
        password: { type: string, in: body, required: true }
      pagination: none

    # =========================================================================
    # CORE -- Data Sources, Jobs, Object Types
    # =========================================================================

    list_data_sources:
      method: GET
      path: /core/data-sources/
      access: read
      description: "List core data sources (git/S3/local paths used to sync templates, scripts, contexts)"
      params:
        name: { type: string, in: query }
        type: { type: string, in: query, description: "git, amazon-s3, local" }
        status: { type: string, in: query, description: "new, queued, syncing, completed, failed" }
        enabled: { type: boolean, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_data_source:
      method: GET
      path: /core/data-sources/{id}/
      access: read
      description: "Get a specific data source"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    create_data_source:
      method: POST
      path: /core/data-sources/
      access: admin
      description: "Create a data source"
      params:
        name: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true, description: "git, amazon-s3, local" }
        source_url: { type: string, in: body, required: true }
        enabled: { type: boolean, in: body, default: true }
        ignore_rules: { type: string, in: body, description: ".gitignore-style rules" }
        parameters: { type: object, in: body, description: "Type-specific config (e.g. {username, password, branch} for git)" }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    update_data_source:
      method: PATCH
      path: /core/data-sources/{id}/
      access: admin
      description: "Update a data source"
      params:
        id: { type: integer, in: path, required: true }
        name: { type: string, in: body }
        type: { type: string, in: body }
        source_url: { type: string, in: body }
        enabled: { type: boolean, in: body }
        ignore_rules: { type: string, in: body }
        parameters: { type: object, in: body }
        description: { type: string, in: body }
        comments: { type: string, in: body }
        tags: { type: array, in: body }
      pagination: none

    delete_data_source:
      method: DELETE
      path: /core/data-sources/{id}/
      access: dangerous
      description: "Delete a data source"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    sync_data_source:
      method: POST
      path: /core/data-sources/{id}/sync/
      access: write
      description: "Enqueue a sync job for the data source. Returns job ID; poll /core/jobs/{id}/."
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_data_files:
      method: GET
      path: /core/data-files/
      access: read
      description: "List data files (read-only listing of files synced from data sources)"
      params:
        source: { type: integer, in: query }
        source_id: { type: integer, in: query }
        path: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_data_file:
      method: GET
      path: /core/data-files/{id}/
      access: read
      description: "Get a specific data file (metadata + content)"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_jobs:
      method: GET
      path: /core/jobs/
      access: read
      description: "List background jobs (script runs, data syncs, etc.)"
      params:
        object_type: { type: string, in: query }
        object_id: { type: integer, in: query }
        status: { type: string, in: query, description: "pending, scheduled, running, completed, errored, failed" }
        user: { type: integer, in: query }
        user_id: { type: integer, in: query }
        name: { type: string, in: query }
        q: { type: string, in: query }
        brief: { type: boolean, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_job:
      method: GET
      path: /core/jobs/{id}/
      access: read
      description: "Get a specific job (status, started/completed times, output data)"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_object_types:
      method: GET
      path: /core/object-types/
      access: read
      description: "List Django ContentTypes (app_label.model strings used in object_type fields)"
      params:
        app_label: { type: string, in: query }
        model: { type: string, in: query }
        q: { type: string, in: query }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    get_object_type:
      method: GET
      path: /core/object-types/{id}/
      access: read
      description: "Get a specific object type"
      params:
        id: { type: integer, in: path, required: true }
      pagination: none

    list_background_queues:
      method: GET
      path: /core/background-queues/
      access: admin
      description: "List RQ background queues with statistics"
      params:
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    list_background_workers:
      method: GET
      path: /core/background-workers/
      access: admin
      description: "List active background workers"
      params:
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

    list_background_tasks:
      method: GET
      path: /core/background-tasks/
      access: admin
      description: "List background tasks (RQ jobs)"
      params:
        queue: { type: string, in: query }
        status: { type: string, in: query, description: "queued, started, finished, failed, deferred, scheduled" }
        limit: { type: integer, in: query }
        offset: { type: integer, in: query }

  examples:
    - name: "Sync VMs from XCP-ng to NetBox"
      description: "List XO VMs and compare with NetBox virtual machines"
      code: |
        const xoVms = await api.list_virtual_machines({ cluster: "xcp-ng" });
        return xoVms;

    - name: "Find free IPs in a subnet"
      description: "Get a prefix by CIDR and list available IPs"
      code: |
        const prefixes = await api.list_prefixes({ prefix: "10.0.1.0/24" });
        if (prefixes.length > 0) {
          return await api.list_available_ips({ id: prefixes[0].id });
        }

    - name: "Document a new server"
      description: "Create device, assign IP, add journal entry"
      code: |
        const device = await api.create_device({
          name: "web-prod-01",
          device_type: 5,
          role: 2,
          site: 1,
          status: "active"
        });
        const iface = await api.list_interfaces({ device_id: device.id });
        await api.create_ip_address({
          address: "10.0.1.50/24",
          assigned_object_type: "dcim.interface",
          assigned_object_id: iface[0].id,
          status: "active"
        });
        await api.create_journal_entry({
          assigned_object_type: "dcim.device",
          assigned_object_id: device.id,
          kind: "success",
          comments: "Server provisioned and IP assigned"
        });
        return device;

    - name: "Network audit"
      description: "List all active devices at a site with their interfaces"
      code: |
        const devices = await api.list_devices({
          site: "dc1", status: "active", brief: true
        });
        const results = [];
        for (const d of devices.slice(0, 10)) {
          const ifaces = await api.list_interfaces({
            device_id: d.id, brief: true
          });
          results.push({ device: d.name, interfaces: ifaces.length });
        }
        return results;

    - name: "Carve a new /26 out of a parent prefix"
      description: "Atomically claim the next free /26 from a parent prefix"
      code: |
        const parents = await api.list_prefixes({ prefix: "10.50.0.0/16" });
        if (!parents.length) return { error: "parent not found" };
        const child = await api.claim_prefix({
          id: parents[0].id,
          prefix_length: 26,
          status: "active",
          description: "Carved for new dev pod"
        });
        return child;

    - name: "Build a virtual chassis"
      description: "Create a 3-member stack with master and assign positions"
      code: |
        const vc = await api.create_virtual_chassis({ name: "core-stack-1", domain: "core" });
        const members = [101, 102, 103];
        for (let i = 0; i < members.length; i++) {
          await api.update_device({
            id: members[i],
            virtual_chassis: vc.id,
            vc_position: i + 1,
            vc_priority: i === 0 ? 255 : 128
          });
        }
        await api.update_virtual_chassis({ id: vc.id, master: members[0] });
        return await api.get_virtual_chassis({ id: vc.id });

    - name: "Reserve rack units"
      description: "Reserve U38-U40 on a rack for an upcoming install"
      code: |
        const racks = await api.list_racks({ name: "DC1-A12", brief: true });
        return await api.create_rack_reservation({
          rack: racks[0].id,
          units: [38, 39, 40],
          user: 1,
          description: "Reserved for new firewall pair"
        });

    - name: "Install a line card module"
      description: "Pick a free module bay and install a module-type"
      code: |
        const bays = await api.list_module_bays({ device: "switch-01", brief: true });
        const free = bays.find(b => !b.installed_module);
        if (!free) return { error: "no free bays" };
        return await api.create_module({
          device: free.device.id,
          module_bay: free.id,
          module_type: 17,
          status: "active",
          serial: "ABC123XYZ"
        });

    - name: "Provision an IPSec site-to-site tunnel"
      description: "Set up IKE/IPSec policies, profile, tunnel, and both terminations"
      code: |
        const ikeProp = await api.create_ike_proposal({
          name: "ike-aes256-sha256",
          authentication_method: "preshared-keys",
          encryption_algorithm: "aes-256-cbc",
          authentication_algorithm: "hmac-sha256",
          group: 14
        });
        const ikePol = await api.create_ike_policy({
          name: "ike-pol-1", version: 2, proposals: [ikeProp.id]
        });
        const ipsecProp = await api.create_ipsec_proposal({
          name: "ipsec-aes256-sha256",
          encryption_algorithm: "aes-256-cbc",
          authentication_algorithm: "hmac-sha256"
        });
        const ipsecPol = await api.create_ipsec_policy({
          name: "ipsec-pol-1", proposals: [ipsecProp.id], pfs_group: 14
        });
        const profile = await api.create_ipsec_profile({
          name: "site-to-site",
          mode: "esp",
          ike_policy: ikePol.id,
          ipsec_policy: ipsecPol.id
        });
        const tunnel = await api.create_tunnel({
          name: "dc1-to-dc2",
          encapsulation: "ipsec-tunnel",
          ipsec_profile: profile.id,
          status: "active"
        });
        await api.create_tunnel_termination({
          tunnel: tunnel.id, role: "peer",
          termination_type: "dcim.interface", termination_id: 4001
        });
        await api.create_tunnel_termination({
          tunnel: tunnel.id, role: "peer",
          termination_type: "dcim.interface", termination_id: 4002
        });
        return tunnel;

    - name: "Run a custom script and wait for completion"
      description: "Execute a NetBox custom script and poll the job until done"
      code: |
        const job = await api.run_script({
          id: 5,
          data: { device_role: "firewall", site: "dc1" },
          commit: true
        });
        let status = job.status;
        for (let i = 0; i < 30 && (status === "running" || status === "pending"); i++) {
          await new Promise(r => setTimeout(r, 2000));
          const j = await api.get_job({ id: job.job_id || job.id });
          status = j.status;
          if (status === "completed" || status === "errored" || status === "failed") return j;
        }
        return { job, final_status: status };

    - name: "Assign a primary contact to a device"
      description: "Create a contact-assignment with the primary role"
      code: |
        const contacts = await api.list_contacts({ name: "Network On-Call", brief: true });
        if (!contacts.length) return { error: "contact not found" };
        return await api.create_contact_assignment({
          object_type: "dcim.device",
          object_id: 1234,
          contact: contacts[0].id,
          priority: "primary"
        });

    - name: "Trace a cable path end to end"
      description: "Follow a port through patch panels to its far end"
      code: |
        return await api.trace_interface({ id: 9001 });