Selector API Usage Guide

Selector System API Usage Information

This document describes Selector API usage for various categories.

Authentication

Bearer Token (using API_KEY placeholder): All API requests require a Bearer token for authentication. In the examples below, replace API_KEY with your actual token. The token is passed in the Authorization header as a Bearer token.

To create your API_Key, go to your profile, then select My API Keys.

Create API Keys

Sample Schema and Base URL

Schema

The following inventory schema is used in API the following examples:

Inventory name: device_test

  • hostname
  • ip
  • region
  • age

Primary keys: hostname and ip

Contents

All the following examples assume that the base URL for the Metastore APIs is:

https://<customer-tenant-name>.selector.ai

The examples in this document use demo.selector.ai as the base URL

The appropriate API endpoint URL must be appended to the base URL when you call the APIs.

Metastore2 Inventory Management APIs Using System ID

This section describes the v1 Inventory management APIs used for managing entries in a device inventory. These entries use the system generated id for inventory management.

Selector customers, please refer to https://<customer-tenant-name>.selector.ai/docs/apis/metastore2-inventory-manager/ for a complete list of Selector Metastore APIs.

Adding an Entry to an Inventory

POST Entry to Inventory

Method/Endpoint: POST /api/inventory-manager**/**v1/inventory/{name}

URL:
https://demo.selector.ai/api/inventory-manager/v1/inventory/device_test

Payload:

{  
    "hostname": "host1",  
    "ip": "10.1.1.1",  
    "region": "us-west",  
    "age": "7"  
}

POST Entry Response (201 OK)

{  
    "message": "Added new item to device_test",  
    "response": {  
        "hostname": "host1",  
        "ip": "10.1.1.1",  
        "region": "us-west",  
        "age": 7,  
        "id": "891e8d7e-cfe7-4f80-896f-52ea7de8zxzb",  
        "__s2_expiry": "2025-07-31T21:52:04.705402+00:00"  
    }  
}

NOTE: For possible error responses, see the section on “Error Handling.”

Back to Contents

Retrieving All Entries in an Inventory

GET All Entries

Method/Endpoint: GET /api/inventory-manager/v1/inventory/{name}

URL:
https://demo.selector.ai/api/inventory-manager/v1/inventory/device_test

GET All Response (201 OK)

[
  {
    "hostname": "host1",
    "ip": "10.1.1.1",
    "region": "us-west",
    "age": "7",
    "_ctime": 1755025254,
    "_utime": 1755025254,
    "id": "c113df4b-03b3-44c2-a353-5837e2608c46"
  },
  {
    "hostname": "host2",
    "ip": "10.1.1.2",
    "region": "us-east",
    "age": "10",
    "_ctime": 1755025273,
    "_utime": 1755025273,
    "id": "d432e4c7-9795-45f7-a2bd-ffa35811d4fc"
  },
  {
    "hostname": "host3",
    "ip": "10.1.1.3",
    "region": "eu-west",
    "age": "7",
    "_ctime": 1755027415,
    "_utime": 1755027415,
    "id": "50566921-ab75-4493-b70c-b32f566d4a40"
  },
  {
    "hostname": "host4",
    "ip": "10.1.1.4",
    "region": "mexico-central",
    "age": "10",
    "_ctime": 1755027712,
    "_utime": 1755027712,
    "id": "105f7c4f-1a65-486d-95fa-54e2cabbae3d"
  }
  {
    "hostname": "host5",
    "ip": "10.1.1.5",
    "region": "us-central",
    "age": "10",
    "_ctime": 1755030717,
    "_utime": 1755030717,
    "id": "b0538634-1085-4534-b889-0b7c2f2ddad1"
  }
]

Back to Contents

Retrieving a Single Entry from an Inventory

GET Single Entry

Method/Endpoint: GET /api/inventory-manager/v1/inventory/{name}/{id}

NOTE: This retrieves a single entry using inventory name and id, which is the ID generated when the entry was first created. See “Adding an Entry to an Inventory.”

URL:
https://demo.selector.ai/api/inventory-manager/v1/inventory/device_test/891e8d7e-cfe7-4f80-896f-52ea7de8df0b

GET Single Response (201 OK)

[
  {
    "hostname": "host1",
    "ip": "10.1.1.1",
    "region": "us-west",
    "age": "7",
    "_ctime": 1755025254,
    "_utime": 1755025254,
    "id": "891e8d7e-cfe7-4f80-896f-52ea7de8df0b "
  }
]

Back to Contents

Modifying a Single Entry in an Inventory

PUT Single Entry

Method/Endpoint: PUT /api/inventory-manager/v1/inventory/{name}/{id} NOTE: This modifies a single entry using inventory name and id, which is the ID generated when the entry was first created. See “Adding an Entry to an Inventory.”

URL:
https://demo.selector.ai/api/inventory-manager/v1/inventory/device_test/b0538634-1085-4534-b889-0b7c2f2ddad1

Payload:

{
  "hostname": "host5",
  "ip": "10.1.1.5",
  "region": "us-central",
  "age": 7
}

PUT Single Response (201 OK)

{
  "message": "Updated item to device_test",
  "response": {
    "hostname": "host5",
    "ip": "10.1.1.5",
    "region": "us-central",
    "age": "7",
    "id": "b0538634-1085-4534-b889-0b7c2f2ddad1",
    "__s2_expiry": "2025-08-12T20:38:36.189678"
  }
}

Back to Contents

Deleting a Single Entry from an Inventory

DELETE Single Entry

Method/Endpoint: DELETE /api/inventory-manager/v1/inventory/{name}/{id} NOTE: This deletes a single entry using inventory name and id, which is the ID generated when the entry was first created. See “Adding an Entry to an Inventory.”

URL:
https://demo.selector.ai/api/inventory-manager/v1/inventory/device_test/b0538634-1085-4534-b889-0b7c2f2ddad1

DELETE Single Response (200 OK)

{
  "message": "Updated item to device_test",
  "response": {
    "hostname": "host5",
    "ip": "10.1.1.5",
    "region": "us-central",
    "age": "7",
    "id": "b0538634-1085-4534-b889-0b7c2f2ddad1"
  }
}

Back to Contents

Metastore2 Inventory Management APIs Using Primary Keys

This section describes how the newer v3 Inventory management APIs that are used with primary keys to manage entries in a device inventory in a simplified manner.

Retrieving a Single Entry in an Inventory

GET Single Primary

With v3 API it is possible to retrieve a single entry in an inventory using all primary keys or with a single primary key when multiple primary keys are present.

Example using ALL primary keys:

Method/Endpoint: GET /api/inventory-manager/v3/inventory/{name}/items?key1=value1&key2=value2… Retrieves a single entry using inventory name and primary keys (hostname and ip)

URL:
https://demo.selector.ai/api/inventory-manager/v3/inventory/device_test?hostname=host1&ip=10.1.1.1

GET Single Primary Response (201 OK)

[
  {
    
    "hostname": "host1",
    "ip": "10.1.1.1",
    "region": "us-west",
    "age": "7",
    "_ctime": 1755025254,
    "_utime": 1755025254,
    "id": "c113df4b-03b3-44c2-a353-5837e2608c46"
  }
]

Back to Contents

Example using a single primary key (but not ALL primary keys, as above):

Method/Endpoint: GET /api/inventory-manager/v3/inventory/{name}/{primary_key1}OR{primary_key2}… Retrieves a single entry using inventory name and any of the primary keys (hostname OR ip)

URL:
https://demo.selector.ai/api/inventory-manager/v3/inventory/device_test/hostname=host1

GET SIngle Primary Response (201 OK)

[
  {
    "hostname": "host1",
    "ip": "10.1.1.1",
    "region": "us-west",
    "age": "7",
    "_ctime": 1755025254,
    "_utime": 1755025254,
    "id": "c113df4b-03b3-44c2-a353-5837e2608c46"
  }
]

Back to Contents

NOTE: In the above example if there are multiple entries for hostname=host1, the response will return all of them.

Back to Contents

Modifying a Single Entry in an Inventory Using Primary

PUT Single Primary Inventory

Method/Endpoint: PUT /api/inventory-manager/v3/inventory/{name}/{primary_key1}&{primary_key2}…. Modifies a single entry using inventory name and primary keys.

URL:
https://demo.selector.ai/api/inventory-manager/v3/inventory/device_test/hostname=host5&ip=10.1.1.5

Payload:

{
  "hostname": "host5",
  "ip": "10.1.1.5",
  "region": "us-central",
  "age": "7"
}
Single Primary Response (201 OK)
{
  "message": "Updated successfully",
  "response": {
    "hostname": "host5",
    "ip": "10.1.1.5",
    "region": "us-central",
    "age": "7",
    "id": "b0538634-1085-4534-b889-0b7c2f2ddad1",
    "__s2_expiry": "2025-08-12T20:38:36.189678"
  }
}

Back to Contents

Deleting a Single Entry from an Inventory Using Primary Keys

DELETE Single Entry Using Primary

Method/Endpoint: DELETE /api/inventory-manager/v3/inventory/{name}/{primary_key1}&{primary_key2}…. Deletes a single entry using inventory name and primary keys

URL:
https://demo.selector.ai/api/inventory-manager/v3/inventory/device_test/hostname=host5&ip=10.1.1.5

DELETE Single Entry Response (200 OK)

 {
  "message": "Deleted successfully from device_test"
  }

Back to Contents

Executing S2QLs with APIs

Selector provides the ability to use APIs to query the data that have been ingested. The APIs wrap the entire command into the payload, allowing a user to either employ a natural language (NL) query or use an S2QL command to obtain the data.

Example of an S2QL command:

S2QL (Selector Query Language) follows this general pattern:

1#select [fields] as [visualization] where [conditions] group-by [fields] order-by [field] top [N]

[fields] specifies which columns to retrieve from which source (table), device, ipaddress in s2_device_inventory

[visualization] specifies how the information is rendered, or displayed.

Selector supports the following:

  • table- Tabular data display
  • timeline-heatmap- Time-series heatmap
  • honeycomb- Honeycomb visualization for health
  • big-text- Large text display for single values
  • topology- Network topology diagram
  • line-plot- Line chart
  • sunburst- Hierarchical sunburst chart
  • event-plot- Event timeline
  • log-table- Log viewer
  • json- Raw JSON output
  • drilldown- Drillable hierarchical view

Filtering with “where” for example where device=FW1

Grouping and aggregation for display, for exsmple group-by site, or group-by type

Ordering and limiting, for example order-by max top 10

Example curl Command

To use a curl command, choose a given widget of interest, then click on the circled “i” for additional information. This provides an option for creating a curl command that leverages the NL Query API:

Using Curl Command

URL:

curl -X POST https://<customer-tenant-name>.selector.ai/api/collab2-slack/rules/command \
-H ‘Authorization: Bearer $APIKEY’ \
-H ‘Content-Type: application/json’ \
-d ‘{“command”:"#select device_harddown_health as honeycomb where site=~CC|CITY\SECTION|SITE|SITE01|SITE02|SITE03|SITE04|SITE05 show-by device, site group-by device, vendor, platform, ipaddress, type, site, os",“utc_offset_sec”:-14400}’

Back to Contents

POST API Example

Method/Endpoint: POST /api/collab2-slack/command

Payload:

{
  "command": "#select device_harddown_health as honeycomb where site=~CC|CITY\SECTION|SITE|SITE01|SITE02|SITE03|SITE04|SITE05 show-by device, site group-by device, vendor, platform, ipaddress, type, site, os",
  "utc_offset_sec": -14400
}

POST RESPONSE (200 OK)

{
  "meta": {
    "render": "honeycomb",
    "threshold": {
      "baseline": "programmed",
      "t0": 0.1,
      "t1": 0.5
    },
    "query": {
      "columns": [
        {
          "name": "device_harddown_health",
          "agg_func": [
            "max"
          ],
          "as_name": "device_harddown_health",
          "alias": null
        },
        {
          "name": "device_harddown_health_color",
          ......
            {
              "name": "long"
            }
          ],
          "render": {
            "annotate": {
              "multiplier": 1,
              "units": "status",
              "values": "device_harddown_health"
            },
            "color-map":,
            "columns": "device",
            "map": {
              "city_geo_codes": [
                {
                  "city": "Phoenix",
                  "lat": 33.5722,
                  "lng": -112.0891,
                  "state_id": "AZ",
                  "state_name": "Arizona"
                },
                {
                  "city": "Las Vegas",
                  "lat": 36.2333,
                  "lng": -115.2654,
                  "state_id": "NV",
                  "state_name": "Nevada"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Back to Contents

Maintenance Window APIs

This section describes the Maintenance Window APIs.

Get Configurations for All Maintenance Windows

GET Maintenance Window Configs

Method/Endpoint: GET /api/apiserver2/api/v2/maintwindow

URL:
https://demo.selector.ai/api/apiserver2/api/v2/maintwindow/

GET Maintenance Window Response (201 OK)

[
  {
    "name": "Global",
    "suppress_alerts": true,
    "global_scope": true,
    "recurring_window": null,
    "description": "User_Test_MW",
    "created_by": "user@example.com",
    "created_at": "2025-08-12 16:09",
    "active": false,
    "alert_name": "user_test_alert",
    "labels": [
      {
        "key": "name",
        "value": [
          "VPN2"
        ]
      }
    ],
    "tags": [],
    "activation_date": "2025-08-12 16:07",
    "timezone": "America/Los_Angeles",
    "end_date": "2025-08-15 16:07",
    "duration_value": 3,
    "duration_units": "d",
    "duration_set": true,
    "recurring": null,
    "uuid": "325f5dfd-645d-4bbc-ada5-0ae511fd3b32",
    "__s2_integration_name": "maintwindow",
    "__s2_obj_version": "v2"
  }
]

Back to Contents

Other Operations for Specific Maintenance Windows

You can execute other maintenance window configuration operations such as POST and GET.

Method/Endpoint: POST /api/apiserver2/api/v2/maintwindow
Method/Endpoint: GET /api/apiserver2/api/v2/maintwindow/{integration_name}

DELETE MW Config

Method/Endpoint: DELETE /api/apiserver2/api/v2/maintwindow/{integration_name}
Deletes the specific maintenance window config with the specified name

URL:
https://demo.selector.ai/internal/apiserver2/api/v2/maintwindow/user_test_MW2

Delete Maintenance Window Response (201 OK)

{
  "message": "Deleted Integration(s) user_test_MW2"
}

Back to Contents

Error Handling

If an operation is unsuccessful, the API returns an error response, typically with a 4xx or 5xx HTTP status code and a JSON body describing the error.

401 Unauthorized or 403 Forbidden

Returned if the Bearer token (represented by API_KEY) is missing, invalid, expired, or lacks permissions for the requested operation.

404 Not Found

Returned if the inventory name or entry ID does not exist.

Example error body: UploadInventoryEntryNotFound: {"message": "Inventory entry does not exist"}
Example error body: UploadInventoryNotFound: {"message": "Table does not exist"}

409 Conflict

Returned if attempting to create an entry with a device_name and device_ip combination that already exists.

422 Unprocessable Entity

Returned if the request body is invalid or missing required fields (for example, missing device_name or device_ip on creation).

Example error body: {"detail": [{"loc": ["body", "device_name"], "msg": "field required", "type": "value_error.missing"}]}

Always check the HTTP status code and the response body for details in case of an error.

Back to Contents