> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt > Use this file to discover all available pages before exploring further. # Run one KnowQL query turn > Send `ask` (the natural-language question) and, when starting a new session, a `scope` of 1–10 contexts. Continue an existing session with `session_id` or `previous_query_id`. Scoped search contexts must be curated (work contexts are queryable immediately), and a scope may not mix work and search contexts. `stream` and `background` are mutually exclusive. With `background: true` the API returns `202` with an `in_progress` query and the client polls `GET /queries/{id}`. With `stream: true` the API emits an SSE stream whose `event:` names are the event `type` (`response.created`, `response.step`, `response.output_text.delta`, `response.turn_rollup`, `response.synthesis`, `response.trace`, and a terminal `response.completed` / `response.failed` / `response.cancelled`), followed by a final `query` event carrying the full query object. Read the answer from `output[].content[].text`. ## OpenAPI ````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml POST /query openapi: 3.0.3 info: title: Nexus API contact: name: Pinecone Support url: https://support.pinecone.io email: support@pinecone.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 2026-07 description: > Nexus turns a set of sources into a queryable, self-improving knowledge base. A context is **sources + a manifest**: upload sources, **curate** them into a searchable index (curate is explicit — there is no auto-curate), and then query the context. The manifest (a single validated JSON document) defines how the context indexes, retrieves, and answers. Conventions: * The `{slug}` path parameter accepts the URL-safe context slug **or** its UUID. * Contexts return a `ContextResponse` (derived flags), not the raw persisted model. Tasks return a `TaskResponse`. * Querying is the unified KnowQL Query API: `POST /api/query` runs one turn (`ask` in, answer out); multi-turn conversations are **sessions** (`GET/DELETE /api/sessions`, `GET /api/queries/{id}`). Read the answer from `output[].content[].text`. * Tasks are a top-level, project-owned resource at `/api/tasks` — they are no longer nested under contexts. Active workflow types are `optimize`, `curate`, `search`, `search_cc`, `search_rag`, `explore`, `profile`, `import`, `pack`, `restore`. servers: - url: https://{host}/api description: Your Nexus deployment host variables: host: default: api.example.com security: - bearerAuth: [] - apiKey: [] tags: - name: Auth description: Login and identity. - name: Project description: The active Pinecone project and its disclosure state. - name: Contexts description: A context is sources + a manifest. Curate it explicitly before querying. - name: Manifest description: Manifest templates and the per-context manifest. - name: Source Files description: >- Per-context source imports (upload, connector, public repo) and the source file tree. - name: Knowledge description: Read-only browse of curated knowledge (chunks + artifacts). - name: Curation description: Curate workflow trigger, curation ledger, and version-pin primitives. - name: Connectors description: >- Project-level links to external source providers (Box, ...). Linked via OAuth or an API key, then used to import source documents into a context. - name: Query description: >- The unified KnowQL Query API: run a query turn (`/query`), fetch a turn (`/queries/{id}`), inspect its trace, manage feedback, comparison flags, and multi-turn sessions (`/sessions`). - name: Tasks description: >- Top-level, project-owned task records for every workflow (optimize, curate, search, work, explore, profile, import, pack, restore, groom). - name: Task Files description: Read, list, and delete files from live or archived task containers. paths: /query: parameters: - $ref: '#/components/parameters/ApiVersionHeader' post: tags: - Query summary: Run one KnowQL query turn description: >- Send `ask` (the natural-language question) and, when starting a new session, a `scope` of 1–10 contexts. Continue an existing session with `session_id` or `previous_query_id`. Scoped search contexts must be curated (work contexts are queryable immediately), and a scope may not mix work and search contexts. `stream` and `background` are mutually exclusive. With `background: true` the API returns `202` with an `in_progress` query and the client polls `GET /queries/{id}`. With `stream: true` the API emits an SSE stream whose `event:` names are the event `type` (`response.created`, `response.step`, `response.output_text.delta`, `response.turn_rollup`, `response.synthesis`, `response.trace`, and a terminal `response.completed` / `response.failed` / `response.cancelled`), followed by a final `query` event carrying the full query object. Read the answer from `output[].content[].text`. operationId: query requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryRequest' responses: '200': description: >- The completed query turn (synchronous), or the SSE stream when `stream=true` content: application/json: schema: $ref: '#/components/schemas/Query' text/event-stream: schema: description: > Server-sent event stream. While the turn runs, each progress frame has an `id:` (the event's sequence number — send it back as the `Last-Event-ID` header to resume), an `event:` name equal to the QueryEvent `type` (e.g. `response.step`), and that QueryEvent as its JSON `data:`. When the turn finishes, a final frame named `event: query` is sent — no `id:`, with the full Query document as `data:`. oneOf: - $ref: '#/components/schemas/QueryEvent' - $ref: '#/components/schemas/Query' '202': description: Accepted (background); poll GET /queries/{id} content: application/json: schema: $ref: '#/components/schemas/Query' '400': description: >- Missing/invalid `ask`, mixed-kind scope, unavailable model, or stream+background together '404': description: Scoped context, session, or previous_query_id not found '409': description: >- A scoped context is not curated, a query is already in flight on the session, or a preview cap was hit '504': description: Turn timed out (15-minute cap, or a lower `timeout_seconds`) components: parameters: ApiVersionHeader: in: header name: X-Pinecone-Api-Version description: >- Date-based contract version. Omit to resolve to the Nexus default version (`2026-07`, the oldest served version); send `unstable` for the in-development surface. The resolved version is echoed back on the same header. A present-but-unrecognized value is rejected with `400 unsupported_api_version`. required: false style: simple schema: type: string default: 2026-07 x-enum: - 2026-07 - unstable schemas: QueryRequest: type: object required: - ask description: >- A single KnowQL query turn. `scope` and the session-config fields (`system_prompt`, `guardrails`, `model`/`models`, `tools`) are honored only when starting a NEW session and are pinned for its life; continue an existing session with `session_id` or `previous_query_id`. The per-turn controls (`workflow`, `shape`, `max_steps`, `thinking_level`, `compose`, `retrieval_only`/`pointers_only`, `chunks_only`/`artifacts_only`, `max_retrieved`/`max_retrieved_chars`) ride the turn and are not pinned to the session. properties: ask: type: string description: The natural-language question scope: type: array minItems: 1 maxItems: 10 items: type: string description: >- Context slugs/UUIDs. New session only; pinned for the session's life. A scope may not mix work and search contexts. session_id: type: string description: Continue an existing session previous_query_id: type: string description: Continue the session this query belongs to workflow: type: string x-enum: - search - search_cc - search_rag description: >- Search workflow for this turn. Legacy aliases `query_search`/`query_sac`, `query_cc`, `query_rag` are still accepted on input. Ignored for work contexts, which always run the `work` runtime. system_prompt: type: string description: Instructions pinned to a new session guardrails: type: string description: Guardrails pinned to a new session shape: type: object additionalProperties: true description: JSON Schema subset for structured output; result in output_json model: type: string description: provider/model models: type: array items: type: string description: Ordered fallback list; takes precedence over model tools: type: array items: type: string stream: type: boolean description: SSE streaming. Mutually exclusive with background. background: type: boolean description: >- Fire-and-forget: 202 + in_progress query; poll GET /queries/{id}. Mutually exclusive with stream. timeout_seconds: type: integer format: int64 description: May only LOWER the 15-minute (900s) cap max_steps: type: integer format: int64 description: Cap the agent's tool-loop steps for this turn thinking_level: type: string x-enum: - minimal - low - medium - high description: >- Gemini reasoning depth. Default `low`. Gemini-backed workflows only; ignored for `search_cc`. compose: type: boolean description: '`false` skips synthesis (alias for `retrieval_only`)' retrieval_only: type: boolean description: Skip synthesis; return retrieved hits in `output_json` pointers_only: type: boolean description: Skip synthesis; return just pointers in `output_json` chunks_only: type: boolean description: Retrieval-only, narrowed to chunks artifacts_only: type: boolean description: Retrieval-only, narrowed to artifacts max_retrieved: type: integer format: int64 description: Cap the item count for retrieval-only turns max_retrieved_chars: type: integer format: int64 description: Cap per-item verbatim text length for retrieval-only turns comparison_group: type: string description: >- Client-generated id shared by the turns of one Compare run, so the preview per-project query cap treats them as a single action. The group is size-bounded server-side (max 3 turns). Omit for a normal single query. Query: type: object required: - id - object - session_id - created - status - input - output - citations - steps - usage - runtime_ms description: One query turn. Read the answer from `output[].content[].text`. properties: id: type: string object: type: string x-enum: - query session_id: type: string model: type: string nullable: true created: type: integer format: int64 description: Unix seconds status: type: string x-enum: - in_progress - completed - failed - cancelled error: type: string nullable: true previous_query_id: type: string nullable: true comparison: type: array nullable: true items: $ref: '#/components/schemas/QueryComparisonMember' feedback: type: object nullable: true required: - rating properties: rating: type: string x-enum: - up - down comment: type: string nullable: true input: type: array description: The stored message array (plain-text `content`). items: type: object required: - role - content properties: role: type: string content: type: string output: type: array description: >- Output items; assistant text is `{role, content:[{type: output_text, text}]}` items: type: object required: - role - content properties: role: type: string content: type: array items: type: object required: - type - text properties: type: type: string example: output_text text: type: string output_json: type: object nullable: true additionalProperties: true description: Present when a shape was used, or on a retrieval-only turn citations: type: array items: $ref: '#/components/schemas/Citation' steps: type: array items: $ref: '#/components/schemas/QueryStep' rollup: type: object nullable: true description: Per-turn token/cache totals + tool tally (`response.turn_rollup`) properties: type: type: string example: response.turn_rollup query_id: type: string cache_read_tokens: type: integer format: int64 cache_write_tokens: type: integer format: int64 n_steps: type: integer format: int64 n_tool_calls: type: integer format: int64 by_category: type: object additionalProperties: type: integer format: int64 total_hits: type: integer format: int64 duration_ms: type: integer format: int64 synthesis: type: object nullable: true description: Token/latency of the answer completion (`response.synthesis`) properties: type: type: string example: response.synthesis query_id: type: string status: type: string tokens_in: type: integer format: int64 tokens_out: type: integer format: int64 ms: type: integer format: int64 answer_preview: type: string tokens_in_cached: type: integer format: int64 tokens_in_cache_write: type: integer format: int64 tokens_in_fresh: type: integer format: int64 trace_ref: type: string nullable: true description: Blob key of the persisted trace usage: type: object required: - input_tokens - output_tokens - total_tokens properties: input_tokens: type: integer format: int64 output_tokens: type: integer format: int64 total_tokens: type: integer format: int64 runtime_ms: type: integer format: int64 QueryEvent: type: object required: - type - query_id description: >- One progress event on a query turn, discriminated by `type`. Emitted as SSE frames on a streaming `POST /query`. properties: type: type: string x-enum: - response.created - response.step - response.output_text.delta - response.turn_rollup - response.synthesis - response.trace - response.completed - response.failed - response.cancelled query_id: type: string session_id: type: string description: '`response.created`' delta: type: string description: '`response.output_text.delta`' error: type: string description: '`response.failed` / `response.cancelled`' trace_ref: type: string description: '`response.trace`' step_id: type: string description: '`response.step`' status: type: string description: >- `response.step` (running/completed/failed), `response.synthesis` (completed) commentary: type: string description: '`response.step`' fns: type: array items: type: string description: '`response.step`' code: type: string description: '`response.step`' cum_input_tokens: type: integer format: int64 description: '`response.step`' cum_output_tokens: type: integer format: int64 description: '`response.step`' n_steps: type: integer format: int64 description: '`response.turn_rollup`' n_tool_calls: type: integer format: int64 description: '`response.turn_rollup`' by_category: type: object additionalProperties: type: integer format: int64 description: '`response.turn_rollup`' total_hits: type: integer format: int64 description: '`response.turn_rollup`' duration_ms: type: integer format: int64 description: '`response.turn_rollup`' cache_read_tokens: type: integer format: int64 description: '`response.turn_rollup`' cache_write_tokens: type: integer format: int64 description: '`response.turn_rollup`' tokens_in: type: integer format: int64 description: '`response.synthesis`' tokens_out: type: integer format: int64 description: '`response.synthesis`' ms: type: integer format: int64 description: '`response.synthesis`' answer_preview: type: string description: '`response.synthesis`' tokens_in_cached: type: integer format: int64 description: '`response.synthesis`' tokens_in_cache_write: type: integer format: int64 description: '`response.synthesis`' tokens_in_fresh: type: integer format: int64 description: '`response.synthesis`' QueryComparisonMember: type: object required: - workflow - query_id properties: workflow: type: string query_id: type: string model: type: string Citation: type: object required: - source description: A cited source in a completed turn's answer. properties: source: type: string section_paths: type: array items: type: array items: type: string description: Heading paths within the source, when known. pages: type: array items: type: integer format: int64 grounding: type: string kind: type: string QueryStep: type: object required: - step_id - status - commentary properties: step_id: type: string status: type: string commentary: type: string fns: type: array items: type: string code: type: string cum_input_tokens: type: integer format: int64 cum_output_tokens: type: integer format: int64 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Session token from POST /auth/login. Pass as `Authorization: Bearer `. The alternative `X-Pinecone-Api-Key` header is also accepted for direct-key auth (used by the Nexus CLI on first contact). apiKey: type: apiKey in: header name: X-Pinecone-Api-Key description: Pinecone API key, accepted as an alternative to the bearer JWT. ````