Back to Docs

Query API

The core endpoint for interacting with Neubot's semantic engine. This endpoint processes natural language queries and returns structured responses, widgets, and thoughts.

Endpoints

POST Process Query

Submit a natural language query for processing.

https://neubot.joshattic.us/api/query

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
}

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.

{
  "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", "media_player", etc.
    "devices": [
      {
        "entity_id": "light.living_room",
        "name": "Living Room",
        "requested_action": "turn_on",
        "success": true,
        "code": 200,
        "state_before": "off",
        "state_current": "on", // included for 'get_state' actions
        "applied_color": "blue",
        "applied_brightness_pct": 50,
        "attributes": {}
      }
    ],
    "applied": {
      "color_name": "blue",
      "brightness_pct": 50
    }
  }
}