Quick Calls

Overview

Quick Calls (the backend entity and API path are quick-actions) are saved, one-click HTTP requests. Each Quick Call is bound to an API Resource — a stored external endpoint that supplies the base_url, authentication, default headers, SSL/timeout settings, and (optionally) a multi-step auth flow. The Quick Call itself only stores the request to send: an HTTP method, a path relative to the resource's base_url, optional headers and body, and an optional json_extract_path that pulls one value out of the response.

Unlike Quick Prompts (which send text to the AI for analysis), a Quick Call fires a real HTTP request against the external system its API Resource points at. You are prompted for any {{variable}} placeholders, the call executes, and the result (status code, raw body, and any extracted value) is returned.

• Bound to an API Resource — the resource holds the base URL and credentials; the Quick Call holds the method, path, headers, and body.
• Variable substitution — {{placeholder}} tokens in the path, header values, and body are replaced at execution time.
• JSON path extraction — an optional dot/bracket path (for example data.result[0].value) pulls a single field out of the JSON response.
• Inline execution — run a saved Quick Call, or send an ad-hoc request against a resource without saving it (execute-inline).

How It Works

A Quick Call is never executed on its own — it always runs through its parent API Resource. At execution time NetStacks:

1. Loads the bound API Resource (api_resource_id) and decrypts its stored credentials.
2. Seeds the variable map with built-in values (the resource's username / password) and, if the resource uses a multi-step auth flow, runs each auth step to obtain a token and stores it under its store_as name.
3. Merges your supplied variables (built-in names cannot be overridden) and substitutes {{name}} placeholders in the path, headers, and body.
4. Builds the URL as base_url + the substituted path, applies the resource default headers, then the Quick Call headers, then the resource auth header (bearer token, basic auth, or API-key header).
5. Sends the request, captures the status code and JSON body, and — if json_extract_path is set — extracts that one value from the body.

Data Model

A Quick Call is stored with the fields below (from the create/update request body). Defaults shown are the server defaults.

Execution Result

Executing a Quick Call returns a result object. There is no table/badge renderer in the model — the client receives the full JSON body plus a single extracted value (when json_extract_path is set) and renders it however it likes.

{
  "success": true,
  "status_code": 200,
  "extracted_value": "10.0.20.0/24",
  "raw_body": {
    "subnet": "10.0.20.0/24",
    "gateway": "10.0.20.1",
    "vlan": 20
  },
  "error": null,
  "duration_ms": 142
}

• success — true when the HTTP status was 2xx.
• status_code — the HTTP status code (0 if the request never completed).
• extracted_value — the value at json_extract_path, or null when no path is set or extraction failed.
• raw_body — the parsed JSON response body (null if the response was not JSON).
• error — an error message on failure (for example HTTP 404 or a transport error), otherwise null.
• duration_ms — request duration in milliseconds.

Creating a Quick Call

Step 1: Create an API Resource first

Quick Calls require an API Resource. Add the external endpoint's base_url, pick an auth type (none, bearer token, basic, API-key header, or a multi-step auth flow), and store its credentials. Set default headers, SSL verification, and a timeout as needed.

Step 2: Add a Quick Call to the resource

From the API Resources view, expand a resource and choose Quick Call, or open Manage Quick Calls from the sidebar / status-bar menu. Give the Quick Call a name.

Step 3: Configure the request

Select the HTTP method and enter the path relative to the resource's base URL (for example /api/v3/ipam/prefixes/). Add request headers and a body if needed. Use {{variable}} tokens anywhere a value should be filled in at run time.

Step 4: Set the JSON extract path (optional)

If you want a single value surfaced from the response, set json_extract_path (for example results[0].prefix). Leave it empty to keep the full response body.

Step 5: Share (Controller only)

Toggle shared to make the Quick Call visible to everyone in your organization. Shared Quick Calls show the owner's name; only the owner can edit or delete them.

Step 6: Test and save

Use inline execution to test the request with sample variable values, confirm the status code and extracted value look right, then save.

Code Examples

All examples assume an API Resource already exists for the target system (it supplies the base_url and auth). The Quick Call path is relative to that base URL.

Look up a NetBox prefix

Query an external NetBox IPAM by VLAN and extract the first prefix from the results array:

{
  "name": "NetBox: prefix for VLAN",
  "description": "Find the IPv4 prefix assigned to a VLAN",
  "api_resource_id": "8f2c0b1e-...-netbox",
  "method": "GET",
  "path": "/api/ipam/prefixes/?vlan_vid={{vlan_id}}",
  "headers": {},
  "body": null,
  "json_extract_path": "results[0].prefix",
  "icon": "search",
  "category": "IPAM",
  "shared": true
}

Create a ticket in an external ITSM

POST a JSON body with variable substitution and extract the new ticket ID:

{
  "name": "Open change ticket",
  "api_resource_id": "1a9d77c4-...-itsm",
  "method": "POST",
  "path": "/api/v2/tickets",
  "headers": {
    "Accept": "application/json"
  },
  "body": "{\"subject\": \"{{summary}}\", \"device\": \"{{device}}\", \"priority\": \"{{priority}}\"}",
  "json_extract_path": "ticket.id",
  "icon": "ticket",
  "category": "Change",
  "shared": true
}

Query an external Prometheus / Grafana datasource

Run a PromQL query and pull the scalar value out of the result vector. The resource's bearer token is applied automatically; only the query and time range are variables:

{
  "name": "Interface utilization (PromQL)",
  "api_resource_id": "c3e5f201-...-prometheus",
  "method": "GET",
  "path": "/api/v1/query?query={{promql}}&time={{at}}",
  "headers": {
    "Accept": "application/json"
  },
  "body": null,
  "json_extract_path": "data.result[0].value[1]",
  "icon": "activity",
  "category": "Monitoring",
  "shared": true
}

Execute a saved Quick Call (curl)

Run a saved Quick Call by ID, passing the variable values. The response is the QuickActionResult shown above:

curl -X POST \
  https://controller.example.com/api/quick-actions/{{action_id}}/execute \
  -H "Authorization: Bearer $NETSTACKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "vlan_id": "20"
    }
  }'

Run an ad-hoc request without saving (execute-inline)

Send a one-off request against an existing API Resource. The path may not contain .. or ://:

curl -X POST \
  https://controller.example.com/api/quick-actions/execute-inline \
  -H "Authorization: Bearer $NETSTACKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_resource_id": "8f2c0b1e-...-netbox",
    "method": "GET",
    "path": "/api/ipam/prefixes/?vlan_vid={{vlan_id}}",
    "headers": {},
    "json_extract_path": "results[0].prefix",
    "variables": { "vlan_id": "20" }
  }'

API Reference

Quick Calls are served from /api/quick-actions (protected, not admin-scoped). Authenticate with a bearer token; results are scoped to your organization and user.

Questions & Answers

Q: What is the difference between Quick Prompts and Quick Calls?

A: Quick Prompts send a text prompt to the AI and return a natural-language answer. Quick Calls execute a real HTTP request against the external system their API Resource points at and return the response. Use Quick Prompts for analysis; use Quick Calls for operational API actions.

Q: Why does a Quick Call need an API Resource?

A: The API Resource holds the base_url, auth type, stored credentials, default headers, SSL setting, timeout, and any multi-step auth flow. The Quick Call only stores the request to send (method, path, headers, body, extract path). This keeps credentials encrypted on the resource and lets many Quick Calls reuse one configured endpoint.

Q: Can Quick Calls hit the NetStacks API itself?

A: Not directly — the path is always appended to the bound resource's base_url, and the inline endpoint rejects paths containing .. or ://. Quick Calls are designed for external systems (IPAM, monitoring, ITSM). To work with devices or stacks, use the Devices API or Stacks API directly.

Q: How does variable substitution work?

A: Tokens use {{variable_name}} and may appear in the path (including query parameters), header values, and body. At execution time the client collects values for each unique token and the server replaces them before sending. Built-in names such as username and password come from the resource credentials and cannot be overridden by user input.

Q: How is the response handled?

A: The result includes status_code, the parsed raw_body, and — when json_extract_path is set — a single extracted_value pulled from that path. There is no built-in table or status-badge renderer; the client displays the body and extracted value.

Q: Can I share Quick Calls with my team?

A: In the Controller, yes. Set shared: true and the Quick Call becomes visible to your whole organization, with the owner's name shown; only the owner can edit or delete it. The standalone free Terminal is single-user, so sharing does not apply there.

Q: How do I run a Quick Call without saving it?

A: Use POST /api/quick-actions/execute-inline with an api_resource_id, the request fields, and a variables map. This is how the UI's inline test runs and how the AI side panel can fire ad-hoc calls against a configured resource.

Troubleshooting

The call fails or returns an error

• Check status_code and error in the result. A non-2xx status sets success: false and error to HTTP <code>.
• Verify the API Resource base_url is reachable and the auth type / stored credentials are correct. For self-signed endpoints, confirm SSL verification is set appropriately on the resource.
• Confirm the HTTP method matches the endpoint (POST to create, GET to read).
• If the request times out, raise the resource timeout_secs.

Variables are not being substituted

• Use double curly braces: {{name}}.
• Make sure every token has a value supplied at run time (or comes from the resource credentials).
• Match names exactly, including case and underscores. You cannot override built-in names like username / password or any auth flow store_as names.

extracted_value is null

• Inspect raw_body and confirm the response is actually JSON (non-JSON responses leave raw_body null). Add an Accept: application/json header if the API needs it.
• Verify json_extract_path matches the real shape: use [n] for array indices and . for keys.
• Temporarily clear json_extract_path to see the full body, then build the path from what you observe.

Inline request rejected

execute-inline returns 400 if the path contains .. or ://. Keep the path relative to the resource base_url.

Related Features

Quick Calls work alongside these features:

• Quick Prompts — saved AI prompt templates for analysis (text in, text out), the text-based counterpart to Quick Calls.
• AI Chat — interactive AI sessions; the side panel can fire inline Quick Calls against a configured API Resource.
• API Authentication — how bearer tokens authenticate calls to the NetStacks API, including the Quick Calls endpoints.
• Devices API — the NetStacks API for device data, for tasks that target devices rather than external systems.
• Stacks API — deploy and manage configuration stacks through the NetStacks API.