NetStacksNetStacks
Contact SalesDownload

Integrations & API Resources

Understand the one building block behind every external connection in NetStacks — the API Resource — and how Integrations, Enrichment, and Quick Calls all build on top of it.

Overview

Almost everything NetStacks does with an external system — NetBox, Netdisco, LibreNMS, a CMDB, SolarWinds, PRTG, or any REST API you own — is built on a single, reusable building block: the API Resource. Understanding this one concept makes the rest of the platform click into place.

An API Resource is a saved external HTTP endpoint: a base URL, an authentication method, and TLS/timeout settings. Its credentials live encrypted in the credential vault. Once you’ve defined an API Resource, three different features can use it — Integrations, Enrichment, and Quick Calls — without you re-entering the URL or token.

The one-sentence mental model

An API Resource is how to reach an external system. An Integration is a feature that knows what to do with a specific system (import devices, pull topology) and uses an API Resource under the hood.

New to APIs? Ask the assistant

Anywhere these settings appear (API Resources, Integrations, Enrichment), you’ll see an “✨ Ask AI” button. It opens a chat that understands these exact concepts and can walk you through setup — even “How do I integrate <my app>?”

How It Works

API Resources — the shared primitive

An API Resource captures everything needed to talk to an endpoint:

  • Base URL — e.g. https://netbox.example.com
  • Auth type — none, bearer token, basic, api-key header, custom header, or a multi-step login flow that extracts a token
  • TLS & timeout — certificate verification and request timeout
  • Credentials — the token/username/password, stored encrypted in the vault (never in plain settings)

You manage API Resources under Settings → API Resources. Each one can be tested against a test path so you know it works before you rely on it.

Integrations wrap an API Resource

An Integration is a named source that points at an API Resource and adds system-specific behavior — dedicated endpoints, typed parsing, and import into first-class NetStacks objects. NetStacks ships three:

  • NetBox (the most full-featured) — imports devices as ready-to-connect sessions, with filters and credential/CLI-flavor mappings. See NetBox Integration.
  • LibreNMS — devices and link/topology import.
  • Crawler — Layer-2 topology and neighbor data. Crawler is simply NetStacks’ UI over Netdisco — you point it at a Netdisco instance. See Network Discovery.
Crawler = Netdisco

The “NetStacks-Crawler” integration talks to Netdisco’s REST API (/api/v1/...). If you already run Netdisco, create an API Resource with your Netdisco host as the base URL and use it as a Crawler source — no separate crawler to deploy.

Enrichment and Quick Calls also use API Resources

The same API Resource can power more than integrations:

  • Enrichment — hover a highlighted token in the terminal (an IP, MAC, or hostname) and NetStacks calls an API Resource to show context inline. See Hover Enrichment.
  • Quick Calls — one-click saved HTTP calls against an API Resource. See Quick Calls.

This is the key insight: an app does not need a built-in integration to be useful in NetStacks. Create one API Resource and you can drive it from Enrichment, Quick Calls, and Methods of Procedure.

Step-by-Step Guide

Integrate any REST application

  1. Open Settings → API Resources and click Add Resource.
  2. Enter the base URL and choose the auth type. For a token API, pick bearer token (or api-key header) and paste the token — it’s stored in the vault.
  3. Set a test path (an endpoint that requires auth, e.g./api/status/) and click Test. A green result confirms the URL, TLS, and credentials all work.
  4. Now use it:
    • Quick Call — save a one-click request against it.
    • Enrichment source — bind it to a token matcher for hover lookups.
    • Integration — if it’s NetBox / Netdisco / LibreNMS, create the matching source.

Connect NetBox (a first-class integration)

  1. Create an API Resource: base URL = your NetBox URL, auth = bearer token = your NetBox API token, test path /api/status/.
  2. Under Settings → Integrations → NetBox Sources, add a source that references that API Resource.
  3. Choose device filters and credential/CLI-flavor mappings, then sync.

Point Crawler at your Netdisco

  1. Create an API Resource: base URL = your Netdisco host, auth = basic or api-key, test path api/v1/device.
  2. Under Settings → Integrations → Crawler Sources, add a source referencing it.

Code Examples

An API Resource is a small, declarative config. A NetBox resource looks roughly like this (the token itself is stored separately, encrypted in the vault):

API Resource (NetBox)json
{
  "name": "NetBox (prod)",
  "base_url": "https://netbox.example.com",
  "auth_type": "bearer_token",
  "verify_ssl": true,
  "timeout_secs": 15,
  "test_path": "/api/status/"
}

When NetStacks calls it, the request it sends is an ordinary authenticated HTTP call — nothing magic:

What NetStacks sendsbash
curl -sS https://netbox.example.com/api/status/ \
  -H "Authorization: Token <your-netbox-api-token>"

An Enrichment source reuses that same resource with a path_template. The token you hover is substituted into the URL:

Enrichment source path templatetext
# Look up the hovered IP in NetBox and show the matching device
/api/ipam/ip-addresses/?address={token}

# {token}, {token_url}, and {session_host} are substituted at hover time

For a Netdisco/Crawler resource, the test path and device endpoint are:

Netdisco (via a Crawler API Resource)bash
curl -sS https://netdisco.example.com/api/v1/device \
  -u "<user>:<pass>"

Questions & Answers

What is the difference between an API Resource and an Integration?
An API Resource is a generic, reusable endpoint definition (URL + auth). An Integration is a feature that adds system-specific behavior — importing devices, pulling topology — and uses an API Resource to reach the system. One API Resource can back an Integration, an Enrichment source, and Quick Calls simultaneously.
My tool isn’t NetBox, Netdisco, or LibreNMS. Can I still integrate it?
Yes. Create an API Resource for it, then use it via a Quick Call, an Enrichment source, or a Method of Procedure step. You do not need a built-in integration.
Is “Crawler” a separate product I have to install?
No. The Crawler integration is NetStacks’ interface to Netdisco. If you already run Netdisco, just create an API Resource pointing at it (test path api/v1/device) and add a Crawler source.
Where do the tokens and passwords go?
Into the encrypted credential vault, never into plain settings. The vault must be unlocked to save or use an API Resource’s credentials.
How do I know an API Resource is configured correctly?
Set a test path (an endpoint that requires authentication) and use the Test button. Testing an open / proves nothing, so NetStacks warns if no meaningful test path is set.
I’m not sure how to start — is there guided help?
Yes. The first-run Setup Wizard covers the essentials, and the ✨ Ask AI buttons throughout Settings open an assistant that understands API Resources, Integrations, and Enrichment and can walk you through any of them.

Troubleshooting

Test fails with 401/403

The credentials or auth type are wrong. Confirm the token is valid and that the auth type matches the API (NetBox uses a bearer/“Token” header; many others use an X-API-Key header or basic auth).

Test succeeds but shows a warning

You likely didn’t set a test path, so NetStacks only reached the base URL. Set a path that requires authentication (e.g./api/status/) and test again.

“Vault is locked” when saving

Credentials are stored in the vault — unlock it first (Settings → Security, or Touch ID on macOS), then save the API Resource.

TLS / self-signed certificate errors

For lab systems with self-signed certs, adjust the API Resource’s TLS verification setting. Prefer installing a trusted certificate for production.