API reference

Search

Run Nexus's internal search and get back ranked document sections, with no LLM answer generated.

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

Workspace

Example request body

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

Search the Onyx index and get back ranked document sections.

Runs the same multi-stage retrieval as the Search action in chat. query expansion, hybrid retrieval, reranking and section merging. and returns the ranked sections without generating an answer. Results are ordered most relevant first and are always filtered by the calling user's document permissions.

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
`query`	string	Yes	Minimum characters: `1`. Maximum characters: `2048`.
`sources`	array of string or null	No	See Request schema.
`document_sets`	array of string or null	No	See Request schema.
`tags`	array of object or null	No	See Request schema.
`time_cutoff`	string or null	No	See Request schema.
`persona_id`	integer or null	No	See Request schema.
`provider`	string or null	No	See Request schema.
`model`	string or null	No	See Request schema.
`skip_query_expansion`	boolean	No	Default: `false`.
`message_history`	array of object or null	No	See Request schema.

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": {
    "query": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "title": "Query"
    },
    "sources": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/DocumentSource"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sources"
    },
    "document_sets": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Sets"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/Tag"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tags"
    },
    "time_cutoff": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Time Cutoff"
    },
    "persona_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Persona Id"
    },
    "provider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Provider"
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model"
    },
    "skip_query_expansion": {
      "type": "boolean",
      "title": "Skip Query Expansion",
      "default": false
    },
    "message_history": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/ChatMinimalTextMessage"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Message History"
    }
  },
  "type": "object",
  "required": [
    "query"
  ],
  "title": "SearchRequest"
}

Responses#

200#

Successful Response

{
  "properties": {
    "results": {
      "items": {
        "$ref": "#/components/schemas/SearchResult"
      },
      "type": "array",
      "title": "Results"
    }
  },
  "type": "object",
  "required": [
    "results"
  ],
  "title": "SearchResponse"
}

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.