> ## 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.

# Nexus quickstart

> Deploy Pinecone Nexus with BYOC, curate a context from your own documents, and run KnowQL queries that return grounded, cited multi-document answers.

Pinecone Nexus runs in your own cloud account. This quickstart deploys Nexus with Bring Your Own Cloud (BYOC), turns a set of your documents into a context, and queries it for grounded, cited answers. It covers both the API and the console, but the rest of the Nexus guides use only the API. See the [overview](https://docs.pinecone.io/guides/nexus/overview.md) for what you can do with Nexus.

Nexus organizes knowledge in a hierarchy:

* A **workspace** holds one or more contexts.
* A **context** is built from the documents you ingest into it.
* A **query** can read one or more contexts, so several contexts together can give an agent its knowledge.

See [key terms](https://docs.pinecone.io/guides/nexus/concepts.md) for the full model.

> [!NOTE]
>
> The examples in this quickstart use a company knowledge base of internal policies for illustration. You bring your own documents, and any set works.

## Prerequisites

* A Pinecone **Enterprise** plan (required for BYOC).
* A dedicated cloud account (AWS, GCP, or Azure) with admin access, plus the install tooling. See the [deploy prerequisites](https://docs.pinecone.io/guides/nexus/byoc/deploy.md#prerequisites) for the full list.
* A [Pinecone API key](https://docs.pinecone.io/reference/api/nexus/authentication.md#get-an-api-key) for the target project.
* Documents to build your context from, such as files to upload or a Hugging Face, GitHub, Box, or Google Drive source.

## 1. Deploy Nexus

Nexus runs in your own cloud, so deploying it comes first.

**1. Install Nexus**

Follow [Deploy Nexus BYOC](https://docs.pinecone.io/guides/nexus/byoc/deploy.md) to install Nexus in your own cloud account with the Pulumi installer.

**2. Get your console URL and API host**

When the install finishes, it prints your workspace console URL and API host. Open the console to work in the UI, or use the host as your data-plane base URL for the API. See [Authentication](https://docs.pinecone.io/reference/api/nexus/authentication.md) to set `NEXUS_BASE_URL` and get a token.

## 2. Add a context

Build a context from your own documents. A company knowledge base might include a refund policy, an expense policy, and a vendor-approval matrix. Nexus ingests dense documents like PDFs directly, alongside Markdown and plain text. For example, two PDFs and a Markdown file could read:

* `policies/refunds.md`: Refund requests must be submitted within 30 days of purchase. After that window, customers receive store credit, not a direct refund.
* `policies/expenses.pdf`: Standard expenses over \$1,000 require manager approval before reimbursement.
* `policies/vendors.pdf`: Vendor invoices over \$10,000 require finance approval. Invoices over \$25,000 also require VP sign-off.

The queries later in this quickstart draw on these files. You can build the context through the API or the console.

> [tab] API
>
> **1. Set your base URL and token**
>
> Point at your workspace host and exchange your Pinecone API key for a session token. See [Authentication](https://docs.pinecone.io/reference/api/nexus/authentication.md) for details.
>
> ```bash theme={null}
> export NEXUS_BASE_URL="https://YOUR_WORKSPACE_HOST/api"
> export NEXUS_TOKEN="$(
>   curl -fsS "$NEXUS_BASE_URL/auth/login" \
>     -H 'Content-Type: application/json' \
>     -H 'X-Pinecone-Api-Version: 2026-07' \
>     -d "{\"api_key\":\"$PINECONE_API_KEY\"}" | jq -r '.token'
> )"
> ```
>
> **2. Create the context**
>
> Create the context with a slug and a name:
>
> ```bash curl theme={null}
> curl -fsS -X POST "$NEXUS_BASE_URL/contexts" \
>   -H "Authorization: Bearer $NEXUS_TOKEN" \
>   -H 'Content-Type: application/json' \
>   -H 'X-Pinecone-Api-Version: 2026-07' \
>   -d '{"slug": "company-knowledge-base", "name": "Company knowledge base"}'
> ```
>
> A new context curates under the default manifest. To define your own artifact and edge types, see [Design your own manifest](https://docs.pinecone.io/guides/nexus/design-your-own-manifest.md).
>
> **3. Add sources**
>
> Upload each of your files, one request per file (archives are expanded automatically), or import from a connector with `POST /contexts/{slug}/import`:
>
> ```bash curl theme={null}
> for f in policies/refunds.md policies/expenses.pdf policies/vendors.pdf; do
>   curl -fsS -X POST "$NEXUS_BASE_URL/contexts/company-knowledge-base/import/upload" \
>     -H "Authorization: Bearer $NEXUS_TOKEN" \
>     -H 'X-Pinecone-Api-Version: 2026-07' \
>     -F "file=@$f"
> done
> ```
>
> **4. Curate**
>
> Curate the context to build its knowledge from the sources:
>
> ```bash curl theme={null}
> curl -fsS -X POST "$NEXUS_BASE_URL/contexts/company-knowledge-base/curate" \
>   -H "Authorization: Bearer $NEXUS_TOKEN" \
>   -H 'Content-Type: application/json' \
>   -H 'X-Pinecone-Api-Version: 2026-07' \
>   -d '{}'
> ```
>
> Curation chunks your sources, distills them into typed artifacts, and indexes everything. It runs as a background task, so query the context once it finishes. See [Nexus curation](https://docs.pinecone.io/guides/nexus/how-curation-works.md).

> [tab] Console
>
> **1. Create the context**
>
> In the console sidebar, next to **Contexts**, click **+ New**. The **New context** dialog opens on the **New context** tab.
>
> Enter a **Name** (for example, `Company knowledge base`) and a **Description**, then click **Create context**. The URL slug is generated from the name.
>
> Creating the context opens a guided setup with three steps: **Add sources**, **Design your context**, and **Review and curate**.
>
> **2. Add sources**
>
> On the **Add sources** step, bring in your documents in one of these ways:
>
> * **Upload** files from your computer, individually or as an archive (`.zip`, `.tar`, `.tar.gz`, or `.tgz`).
> * Pull from a public **Hugging Face** or **GitHub** repository URL.
> * Connect a **Box** or **Google Drive** account.
>
> After you add at least one source, click **Design your context**.
>
> **3. Design your context**
>
> On the **Design your context** step, Nexus scans your sources and suggests [manifest](https://docs.pinecone.io/guides/nexus/context-design.md) templates that match. Each template describes the artifacts and edges it'll build.
>
> Pick a template that fits, such as **General knowledge base**. If none fit, pick the closest one and adjust its artifact and edge types later on the context's **Manifest** tab, or [design your own manifest](https://docs.pinecone.io/guides/nexus/design-your-own-manifest.md) through the API.
>
> Click **Review**.
>
> **4. Curate**
>
> On the **Review and curate** step, check the artifact types, edge types, model, and estimated cost, then click **Save and curate**. The curation task opens.
>
> Nexus [curates](https://docs.pinecone.io/guides/nexus/how-curation-works.md) your sources. It chunks them, distills them into the typed artifacts the manifest defines, then indexes everything.
>
> Curation runs in the background, so you can leave the task and return to the context while it works.
>
> > [!TIP]
> >
> > Have a `.context.zip` pack? In the **New context** dialog, open the **Restore** tab, drop the pack (or click **choose a file**), then click **Restore context**. Packs come from a context's **Packs** tab.

## 3. Query your context

Once curation finishes, ask your context a question and get back a grounded answer with citations.

> [tab] API
>
> Send a [KnowQL](https://docs.pinecone.io/guides/nexus/concepts.md#knowql) query over HTTP, passing the context slug as `scope`:
>
> ```bash curl theme={null}
> curl -fsS -X POST "$NEXUS_BASE_URL/query" \
>   -H "Authorization: Bearer $NEXUS_TOKEN" \
>   -H 'X-Pinecone-Api-Version: 2026-07' \
>   -H 'Content-Type: application/json' \
>   -d '{"scope": ["company-knowledge-base"], "ask": "What is the refund policy?"}' \
> | jq -r '.output[].content[].text'
> ```
>
> ```console Output theme={null}
> Refund requests must be submitted within 30 days of purchase. After that
> window, customers can still get store credit, but not a direct refund.
> ```
>
> The full response also carries `citations` and `usage`. See the [Nexus API](https://docs.pinecone.io/reference/api/nexus/introduction.md) for the full surface, or connect an [MCP](https://modelcontextprotocol.io) client such as Claude Desktop with the [Nexus MCP server](https://docs.pinecone.io/guides/nexus/mcp-server.md).

> [tab] Console
>
> **1. Open the context**
>
> Use **Query this context** on the curation task, or open the context anytime from the console sidebar. The context opens on the **Query** tab.
>
> **2. Ask a question**
>
> In the **Query this context** box on the **Query** tab, type your question and run it. You can also pick the answering **model**.

> [!TIP]
>
> To query several contexts at once, pass multiple slugs in the query's `scope` array. In the console, start a session from **Sessions** with **+ New session** and select each context to query across.

### A grounded, cited answer

Nexus plans its own retrieval across the context's curated knowledge, gathers the relevant evidence, and composes a single grounded answer with inline citations. Asking the company knowledge base "What is the refund policy?" returns something like:

> Refund requests must be submitted within 30 days of purchase. After that window, customers can still get store credit, but not a direct refund. **\[1]**
>
> **\[1]** `policies/refunds.md`

The answer is grounded in your sources, and every claim cites the document it came from, so you can check it. To see how Nexus produced it, open the query's [trace](https://docs.pinecone.io/guides/nexus/query-tracing.md). In the console, Nexus also suggests follow-up topics and saves the query as a session you can reopen from **Sessions**.

### A multi-document answer

Questions that span multiple documents work the same way. Asking "Which purchases need approval, and what's the threshold for each?" returns something like:

> * Standard expenses over \$1,000 need manager approval. **\[1]**
> * Vendor invoices over \$10,000 need finance approval. **\[2]**
> * Vendor invoices over \$25,000 need VP and finance approval. **\[2]**
>
> **\[1]** `policies/expenses.pdf`  **\[2]** `policies/vendors.pdf`

To answer this, Nexus draws on the artifacts it compiled from your policies during curation, gathering the matching rules from across your documents, each with its own citation. A plain RAG search returns only the passages closest to your question, so it can miss rules in other documents. Reaching across your whole corpus is a core reason to use Nexus over RAG. For exact counts and enumerations over structured data, define a SQLite artifact, covered in [artifact formats](https://docs.pinecone.io/guides/nexus/configure-artifact-formats.md). See [how queries work](https://docs.pinecone.io/guides/nexus/queries.md) for what the runtime does on each turn, or the [overview](https://docs.pinecone.io/guides/nexus/overview.md#what-nexus-is-not) for how Nexus compares to RAG.
