openapi: 3.1.0
info:
  title: Cradlepoint NetCloud Manager API v2
  description: |
    RESTful API to the Cradlepoint NetCloud Manager (NCM) platform. Lets
    client applications perform programmatically many of the same operations
    available in the NCM user interface: enumerate accounts, manage routers
    and groups, configure them, listen to alerts, ingest device telemetry,
    track location history, and administer users and subscriptions.

    Authentication uses two header pairs sent on every request:
      * X-CP-API-ID / X-CP-API-KEY — Cradlepoint API keys (account-level,
        used for API-usage tracking, available from the Getting Started page
        of developer.cradlepoint.com).
      * X-ECM-API-ID / X-ECM-API-KEY — NetCloud (ECM) API keys generated by
        an NCM administrator from the Tools tab in NCM. These keys carry the
        NCM role assignment (Administrator, Full Access User, Read Only User,
        Diagnostic User) and authorize what the request can do.
  version: '2.0'
  contact:
    name: Ericsson Enterprise Wireless / Cradlepoint Support
    url: https://customer.cradlepoint.com/
  termsOfService: https://cradlepoint.com/about-us/legal/

servers:
  - url: https://www.cradlepointecm.com/api/v2
    description: NetCloud Manager Production

security:
  - CradlepointApiKey: []
    NetCloudApiKey: []

tags:
  - name: Accounts
    description: Account and subaccount management
  - name: ActivityLogs
    description: Audit / activity logs across accounts
  - name: Alerts
    description: Generated alerts
  - name: AlertRules
    description: Alert monitoring rule configuration
  - name: AlertPushDestinations
    description: Outbound webhook destinations for alert delivery
  - name: Groups
    description: Logical device groupings
  - name: Routers
    description: Router (edge device) management
  - name: NetDevices
    description: Modems, WAN devices, and network interfaces on routers
  - name: Locations
    description: Current and historical router location

paths:
  /accounts/:
    get:
      summary: List Accounts
      description: List accounts and subaccounts visible to the authenticated NCM keys.
      operationId: listAccounts
      tags: [Accounts]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountList'
  /accounts/{id}/:
    get:
      summary: Get An Account
      description: Retrieve a single account by ID.
      operationId: getAccount
      tags: [Accounts]
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'

  /activity_logs/:
    get:
      summary: List Activity Logs
      description: View activities and changes within the authenticated account.
      operationId: listActivityLogs
      tags: [ActivityLogs]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of activity-log entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityLogList'

  /alerts/:
    get:
      summary: List Alerts
      description: View alerts that have been generated in the account.
      operationId: listAlerts
      tags: [Alerts]
      parameters:
        - name: type
          in: query
          schema: { type: string }
        - name: created_at__gt
          in: query
          schema: { type: string, format: date-time }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of alerts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertList'

  /alert_rules/:
    get:
      summary: List Alert Rules
      description: Alert-rule definitions monitoring health and status of the account.
      operationId: listAlertRules
      tags: [AlertRules]
      responses:
        '200':
          description: Alert rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRuleList'
    post:
      summary: Create An Alert Rule
      description: Configure a new alert rule.
      operationId: createAlertRule
      tags: [AlertRules]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertRule'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRule'

  /alert_push_destinations/:
    get:
      summary: List Alert Push Destinations
      description: Configured outbound HTTP destinations (webhooks) for alert delivery.
      operationId: listAlertPushDestinations
      tags: [AlertPushDestinations]
      responses:
        '200':
          description: Push destinations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertPushDestinationList'
    post:
      summary: Create An Alert Push Destination
      description: Register a webhook URL that should receive alert JSON payloads.
      operationId: createAlertPushDestination
      tags: [AlertPushDestinations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertPushDestination'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertPushDestination'

  /groups/:
    get:
      summary: List Groups
      description: Logical device groupings used to share configuration.
      operationId: listGroups
      tags: [Groups]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'

  /routers/:
    get:
      summary: List Routers
      description: List routers visible to the authenticated NCM keys.
      operationId: listRouters
      tags: [Routers]
      parameters:
        - name: state
          in: query
          schema: { type: string, enum: [online, offline, unknown] }
        - name: group
          in: query
          schema: { type: string }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of routers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouterList'
  /routers/{id}/:
    get:
      summary: Get A Router
      description: Retrieve a single router by ID.
      operationId: getRouter
      tags: [Routers]
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Router
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Router'
    patch:
      summary: Update A Router
      description: Update editable router fields such as `name`, `description`, `group`.
      operationId: updateRouter
      tags: [Routers]
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Router'
      responses:
        '200':
          description: Updated router
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Router'

  /net_devices/:
    get:
      summary: List Net Devices
      description: Modems and network interfaces (WAN, LAN, modem, ethernet) on routers.
      operationId: listNetDevices
      tags: [NetDevices]
      parameters:
        - name: router
          in: query
          schema: { type: string }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of net devices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetDeviceList'

  /historical_locations/:
    get:
      summary: List Historical Locations
      description: Time-stamped GPS / location samples for routers (vehicle / mobile fleet use case).
      operationId: listHistoricalLocations
      tags: [Locations]
      parameters:
        - name: router
          in: query
          schema: { type: string }
        - name: created_at__gt
          in: query
          schema: { type: string, format: date-time }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of historical location samples.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalLocationList'

components:
  securitySchemes:
    CradlepointApiKey:
      type: apiKey
      in: header
      name: X-CP-API-ID
      description: Cradlepoint account API ID (paired with X-CP-API-KEY).
    NetCloudApiKey:
      type: apiKey
      in: header
      name: X-ECM-API-ID
      description: NCM tenant API ID (paired with X-ECM-API-KEY), carries the NCM role.

  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of records to return per page.
      schema:
        type: integer
        default: 20
        maximum: 500
    Offset:
      name: offset
      in: query
      description: Number of records to skip for pagination.
      schema:
        type: integer
        default: 0
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string

  schemas:
    Account:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        parent_account: { type: string, nullable: true }
        created_at: { type: string, format: date-time }
        is_active: { type: boolean }
    AccountList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Account' }
        meta:
          $ref: '#/components/schemas/Meta'

    ActivityLog:
      type: object
      properties:
        id: { type: string }
        account: { type: string }
        actor: { type: string }
        action: { type: string }
        target: { type: string }
        created_at: { type: string, format: date-time }
    ActivityLogList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/ActivityLog' }
        meta: { $ref: '#/components/schemas/Meta' }

    Alert:
      type: object
      properties:
        id: { type: string }
        account: { type: string }
        router: { type: string }
        type: { type: string, description: 'e.g. router_offline, signal_degraded, config_changed' }
        message: { type: string }
        severity: { type: string, enum: [info, warning, error, critical] }
        created_at: { type: string, format: date-time }
        acknowledged_at: { type: string, format: date-time, nullable: true }
    AlertList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Alert' }
        meta: { $ref: '#/components/schemas/Meta' }

    AlertRule:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string }
        enabled: { type: boolean }
        scope: { type: string, description: 'account, group, or router' }
        target: { type: string }
        push_destinations:
          type: array
          items: { type: string }
        created_at: { type: string, format: date-time }
    AlertRuleList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/AlertRule' }
        meta: { $ref: '#/components/schemas/Meta' }

    AlertPushDestination:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        url: { type: string, format: uri }
        method: { type: string, enum: [POST, PUT], default: POST }
        headers:
          type: object
          additionalProperties: { type: string }
        enabled: { type: boolean }
    AlertPushDestinationList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/AlertPushDestination' }
        meta: { $ref: '#/components/schemas/Meta' }

    Group:
      type: object
      properties:
        id: { type: string }
        account: { type: string }
        name: { type: string }
        product: { type: string, description: 'router product line, e.g. IBR1700, E300, E3000' }
        target_firmware: { type: string }
        config:
          type: object
          additionalProperties: true
    GroupList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Group' }
        meta: { $ref: '#/components/schemas/Meta' }

    Router:
      type: object
      properties:
        id: { type: string }
        account: { type: string }
        group: { type: string, nullable: true }
        name: { type: string }
        description: { type: string }
        mac: { type: string }
        serial_number: { type: string }
        product: { type: string }
        actual_firmware: { type: string }
        state: { type: string, enum: [online, offline, unknown] }
        last_seen_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
    RouterList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Router' }
        meta: { $ref: '#/components/schemas/Meta' }

    NetDevice:
      type: object
      properties:
        id: { type: string }
        router: { type: string }
        type: { type: string, description: 'modem, ethernet, lan, wan' }
        connection_state: { type: string }
        carrier: { type: string }
        homecarrier: { type: string }
        signal_strength: { type: integer }
        rsrp: { type: integer }
        rsrq: { type: integer }
        iccid: { type: string }
        imei: { type: string }
        ipv4_address: { type: string }
    NetDeviceList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/NetDevice' }
        meta: { $ref: '#/components/schemas/Meta' }

    HistoricalLocation:
      type: object
      properties:
        id: { type: string }
        router: { type: string }
        latitude: { type: number, format: float }
        longitude: { type: number, format: float }
        accuracy: { type: number, format: float }
        speed: { type: number, format: float }
        heading: { type: number, format: float }
        created_at: { type: string, format: date-time }
    HistoricalLocationList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/HistoricalLocation' }
        meta: { $ref: '#/components/schemas/Meta' }

    Meta:
      type: object
      properties:
        limit: { type: integer }
        offset: { type: integer }
        total_count: { type: integer }
        next: { type: string, nullable: true }
        previous: { type: string, nullable: true }