Back to Docs

Query API

The core endpoint for interacting with neubot. This endpoint processes natural language queries and returns structured responses, widgets, and thoughts.

---

Endpoints

POST Process Query

Submit a natural language query for processing.

Headers

Header	Value	Required	Description
Authorization	Bearer <token>	Yes	Authentication token.
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
query	string	Yes	The natural language text to process (e.g., "What's the weather?").
timezone	string	No	IANA timezone identifier (e.g., "America/New_York"). Used for date/time calculations. Defaults to server setting if omitted.

Response Schema

{
  "response": "The weather in New York is sunny...",  // The spoken/text response
  "widgets": [                                        // UI widgets to display
    {
      "type": "weather",
      "data": { ... }
    }
  ],
  "thoughts": [ ... ],                                // Reasoning trace (if authorized)
  "highlightedQuery": "What's the weather?" // HTML string with entity highlighting
}

---

POST Register Session Client Skills

Declare non-executable native client skills for the current session. Neubot will check these during query parsing and respond with structured client command instructions.

Body Parameters

Parameter	Type	Required	Description
skills	array	Yes	List of skill objects (each containing name, triggers, parameters, and response_template).
session_id	string	No	Session identifier. Defaults to request user/IP session if omitted.

Example Request

{
  "session_id": "session-123",
  "skills": [
    {
      "name": "set_timer",
      "triggers": ["set a timer for", "set timer for"],
      "parameters": [
        {
          "name": "duration",
          "extract_regex": "\\b(\\d+\\s*(?:minutes?|seconds?|hours?))\\b"
        }
      ],
      "response_template": "Setting a timer for {duration} on your device."
    }
  ]
}

---

POST Home Assistant Manual Entity Control

Manually toggle or control a specific Home Assistant device without natural language parsing.

Headers

Header	Value	Required	Description
Authorization	Bearer <token>	Yes	Authentication token or session cookie.
Content-Type	application/json	Yes	Must be application/json.

Body Parameters

Parameter	Type	Required	Description
entity_id	string	Yes	The Home Assistant entity ID (e.g., light.desk_lamp, switch.fan, fan.bedroom).
action	string	Yes	Service action to perform (e.g., turn_on, turn_off, or toggle).
brightness	integer	No	Brightness percentage from 1 to 100 (supported for light entities).
color	string | array	No	Light color. Accepts hex string (e.g. "#ff0000"), color name (e.g. "red", "warm white"), or RGB tuple/array (e.g. [255, 0, 0]).

Example Request

{
  "entity_id": "light.desk_lamp",
  "action": "turn_on",
  "brightness": 75,
  "color": "#ffaa00"
}

Example Response (Success)

{
  "success": true
}

Example Response (Error)

{
  "success": false,
  "error": "HA service returned 502"
}

---

Widget Schemas

The widgets array optionally contains structured data objects for UI rendering. Below are the definitions for the supported widget types.

Weather Widget

type: "weather" -- Returned for weather-related queries.

{
  "type": "weather",
  "data": {
    "location": "New York",
    "condition": "Cloudy",
    "temperature": {
      "celsius": 15.2,
      "fahrenheit": 59.4
    },
    "humidity": 65,
    "description": "The weather in New York is Cloudy with a temperature of..."
  }
}

Search Results Widget

type: "search_results" -- Returned for general knowledge queries or explicit search requests.

{
  "type": "search_results",
  "data": {
    "query": "search query",
    "spellcheck": null,
    "results": [
      {
        "title": "Page Title",
        "url": "https://example.com",
        "description": "Snippet of content from the page...",
        "favicon": "https://example.com/favicon.ico"
      }
    ],
    "meta": {
      "total": 5,
      "header": "Here's what I found on the web for \"search query\""
    }
  }
}

Home Assistant Widget

type: "home_assistant" -- Returned for smart home control actions and sensor queries.

{
  "type": "home_assistant",
  "data": {
    "summary": "I turned on the Living Room Light.",
    "action": "turn_on", // "turn_on", "turn_off", "get_state", "multi"
    "domain": "light",     // "light", "switch", "fan", "sensor", "binary_sensor", etc.
    "devices": [
      {
        "entity_id": "light.living_room",
        "name": "Living Room Light",
        "requested_action": "turn_on",
        "success": true,
        "code": 200,
        "state_before": "off",
        "state_current": "on", // Current state of the entity
        "applied_color": "warm white",
        "applied_brightness_pct": 50,
        "attributes": {}
      }
    ],
    "applied": {
      "color_name": "warm white",
      "brightness_pct": 50,
      "restore_in_seconds": 0
    }
  }
}

Client Command Widget

type: "client_command" -- Returned when a declared native client skill is matched during natural language query parsing.

{
  "type": "client_command",
  "data": {
    "command": "set_timer",
    "parameters": {
      "duration": "10 minutes"
    }
  }
}