API reference

Execute Web Search

Perform a web search and immediately fetch content for the returned URLs.

Before you begin

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

POST/web-search/search

Workspace

Example request body

curl --request POST 'https://school.narb.cc/api/web-search/search' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "queries": [
    "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.

Perform a web search and immediately fetch content for the returned URLs.

Use this when you want both snippets and page contents from one call.

If you want to selectively fetch content (i.e. let the LLM decide which URLs to read), use /search-lite and then call /open-urls separately.

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
`queries`	array of string	Yes	List of search queries to send to the configured provider. Minimum items: `1`.
`max_results`	integer or null	No	Optional cap on number of results to return per query. Defaults to 10. Default: `10`.

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": {
    "queries": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "minItems": 1,
      "title": "Queries",
      "description": "List of search queries to send to the configured provider."
    },
    "max_results": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Results",
      "description": "Optional cap on number of results to return per query. Defaults to 10.",
      "default": 10
    }
  },
  "type": "object",
  "required": [
    "queries"
  ],
  "title": "WebSearchToolRequest"
}

Responses#

200#

Successful Response

{
  "properties": {
    "search_provider_type": {
      "$ref": "#/components/schemas/WebSearchProviderType"
    },
    "content_provider_type": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/WebContentProviderType"
        },
        {
          "type": "null"
        }
      ]
    },
    "search_results": {
      "items": {
        "$ref": "#/components/schemas/LlmWebSearchResult"
      },
      "type": "array",
      "title": "Search Results"
    },
    "full_content_results": {
      "items": {
        "$ref": "#/components/schemas/LlmOpenUrlResult"
      },
      "type": "array",
      "title": "Full Content Results"
    }
  },
  "type": "object",
  "required": [
    "search_provider_type",
    "search_results",
    "full_content_results"
  ],
  "title": "WebSearchWithContentResponse"
}

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.