You can query a Nexus knowledge base over HTTP via a unified KnowQL Query API. You send a question scoped to one or more contexts; Nexus plans its own retrieval over those contexts and returns a grounded answer with citations. Auth and endpoints are ready — set the token once:

export NEXUS_TOKEN=""

Step 1 — pick the context(s) to query. A query is scoped to one or more contexts, identified by their "slug". These contexts are available to this token:

(none curated yet — curate a context first, or list them at runtime with the call below)

Ask the user which of these to query — they may pick one or up to 10 — and use the chosen slug(s) as the "scope" below. If the user's intent clearly matches a single context, you may proceed with it and confirm. (To re-list at runtime: curl -s "https://prod.nexus.pinecone.io/api/v0/contexts" -H "Authorization: Bearer $NEXUS_TOKEN" — only curated contexts are queryable.)

Step 2 — submit the question (async). A query plans and runs its own multi-step retrieval, so it typically takes 20–60 seconds (hard cap 15 min) — too long to wait on a synchronous POST, which will often hit an intermediate HTTP timeout. So submit with "background": true: the POST returns immediately (HTTP 202) with a query object whose "status" is "in_progress" and whose "id" you then poll (there is no webhook). Pass the slug(s) from step 1 as "scope":

curl -s -X POST "https://prod.nexus.pinecone.io/api/v0/query" -H "Authorization: Bearer $NEXUS_TOKEN" -H "Content-Type: application/json" \
  -d '{"ask": "<the user question>", "scope": ["<context-slug-from-step-1>"], "background": true}'

Step 3 — poll until done. Re-fetch the query by its id every few seconds until "status" is "completed" or "failed" (results persist, so poll as long as you need):

curl -s "https://prod.nexus.pinecone.io/api/v0/queries/<query id>" -H "Authorization: Bearer $NEXUS_TOKEN"

Step 4 — read the result. When "status" is "completed": read the answer from output[].content[].text (the output_text parts), citations from "citations", and keep "session_id" to continue the conversation. If a "shape" was supplied, the structured result is in "output_json". When "status" is "failed", read "error".

Multi-turn: continue the same session by passing its session_id (Nexus keeps conversational context across turns); you don't need to repeat scope. Use background + poll here too.

curl -s -X POST "https://prod.nexus.pinecone.io/api/v0/query" -H "Authorization: Bearer $NEXUS_TOKEN" -H "Content-Type: application/json" \
  -d '{"ask": "<the follow-up question>", "session_id": "<session id>", "background": true}'

Other body params: ask (the question), scope (1–10 context slugs/UUIDs, new session only), session_id / previous_query_id (continue a session), system_prompt, guardrails, shape (JSON Schema for structured output), model / models (provider/model selection; models is an ordered fallback list), tools, background (async; 202 + poll GET /api/v0/queries/{id}), stream (SSE; mutually exclusive with background), timeout_seconds (lower the 15-min cap).

Failure handling (any call): no HTTP status (DNS/timeout/refused) or 403 means egress is blocked, not bad auth — allowlist prod.nexus.pinecone.io (personal Claude plans: Settings → Capabilities → Network, then start a new chat) or ask your admin, then retry. 401 = bad token, 5xx = server error: report and stop.