API reference

Handle Send Search Message

Executes a search query with optional streaming.

Before you begin

This page uses Nexus's generated request and response schema. Requests still require the correct account, workspace, and resource permissions.

POST/search/send-search-message

Workspace

Example request body

curl --request POST 'https://school.narb.cc/api/search/send-search-message' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "search_query": "example"
}'

This builds a request example. Fill in required query values, then replace path placeholders and YOUR_TOKEN in your own environment. Use a token for a user with access to this workspace. Responses and permissions depend on your account and deployment. Never paste a private token into documentation.

Download the Nexus OpenAPI schema ↗
Import the schema into your API client. It describes the backend source; enabled routes depend on your workspace.

Authentication and scope#

Send requests to the workspace that owns the resource. Authentication does not by itself grant a school membership, class assignment, or administrator permission. School endpoints apply their role and class checks on the server.

Use a credential issued for that workspace with only the permissions your integration needs. Keep it on your server. Do not place credentials in a public website or a shared skill.

Executes a search query with optional streaming.

If hybrid_alpha is unset and ONYX_SEARCH_UI_USES_OPENSEARCH_KEYWORD_SEARCH is True, executes pure keyword search.

Returns: StreamingResponse with SSE if stream=True, otherwise SearchFullResponse.

Parameters#

Name	Location	Required	Type
`tenant_id`	query	No	string or null

The tenant_id parameter is part of the engine schema. It does not authorize a caller to another school. Use the workspace and permissions assigned to your account.

Request body#

Content type: application/json.

Field	Type	Required	Details
`search_query`	string	Yes	See Request schema.
`filters`	object or null	No	See Request schema.
`num_docs_fed_to_llm_selection`	integer or null	No	See Request schema.
`run_query_expansion`	boolean	No	Default: `false`.
`num_hits`	integer	No	Default: `30`.
`hybrid_alpha`	number or null	No	See Request schema.
`include_content`	boolean	No	Default: `false`.
`stream`	boolean	No	Default: `false`.

Request schema#

The schema includes field limits and required values. Referenced types are included in the downloadable OpenAPI file. Replace example identifiers with IDs from your workspace.

{
  "properties": {
    "search_query": {
      "type": "string",
      "title": "Search Query"
    },
    "filters": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BaseFilters"
        },
        {
          "type": "null"
        }
      ]
    },
    "num_docs_fed_to_llm_selection": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Num Docs Fed To Llm Selection"
    },
    "run_query_expansion": {
      "type": "boolean",
      "title": "Run Query Expansion",
      "default": false
    },
    "num_hits": {
      "type": "integer",
      "title": "Num Hits",
      "default": 30
    },
    "hybrid_alpha": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hybrid Alpha"
    },
    "include_content": {
      "type": "boolean",
      "title": "Include Content",
      "default": false
    },
    "stream": {
      "type": "boolean",
      "title": "Stream",
      "default": false
    }
  },
  "type": "object",
  "required": [
    "search_query"
  ],
  "title": "SendSearchQueryRequest"
}

Responses#

200#

If stream=true, returns text/event-stream. If stream=false (the default), returns application/json (SearchFullResponse).

{
  "properties": {
    "all_executed_queries": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "All Executed Queries"
    },
    "search_docs": {
      "items": {
        "$ref": "#/components/schemas/SearchDocWithContent"
      },
      "type": "array",
      "title": "Search Docs"
    },
    "doc_selection_reasoning": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Doc Selection Reasoning"
    },
    "llm_selected_doc_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Llm Selected Doc Ids"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error"
    }
  },
  "type": "object",
  "required": [
    "all_executed_queries",
    "search_docs"
  ],
  "title": "SearchFullResponse"
}

422#

Validation Error

{
  "properties": {
    "detail": {
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

Access and error handling#

A signed-out or expired session needs authentication. A denied request can mean the account lacks permission, class membership, an approved model, or an available allowance. Do not retry a write blindly after a network failure; first check whether it was recorded.

Treat validation errors as a request problem. Use the returned field details to correct the request. Resource identifiers do not confer access.

Schema version#

Generated from Nexus backend source fe1c3a07c793029d3d87191a68f89e481afd6bc8. Check your deployed version before integrating. Schema coverage is not a live acceptance test.