Update API Reference section with improved structure and flow

www/docs/api-reference/admin-apis/admin.md

@@ -1,7 +1,7 @@
 ---
 id: admin
-title: Corpus Administration APIs
-sidebar_label: Corpus Administration APIs
+title: Corpus Administration
+sidebar_label: Corpus Administration
 ---
 
 import Tabs from '@theme/Tabs';
@@ -13,24 +13,25 @@ The Vectara Console is a good way for you to get started with <Config v="names.p
 you're ready to integrate the platform more deeply into your application, the 
 Corpus Admin APIs allow you to programmatically manipulate corpora and perform 
 many other operations within the system. These APIs enable new workflows for 
-organizations, like tracking usage of accounts and corpora. Check out this [blog post about managing multi-tenancy](https://vectara.com/managing-multi-tenancy-with-vectaras-new-management-apis/) for more details.
+organizations, like managing corpora and tracking usage of accounts 
+and corpora. Check out this [blog post about managing multi-tenancy](https://vectara.com/blog/managing-multi-tenancy-with-vectaras-new-management-apis/) for more details.
 
 :::tip
 
 The [**interactive API Playground**](/docs/rest-api/admin-service) lets you experiment with these API endpoints.
 
 :::
 
-## Create, Delete, and Reset API Definitions
+## Create, Delete, and Reset Corpus API Definitions
 
 The full definitions of the Create, Reset, and Delete gRPC APIs are covered
 in [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto). 
 
-* The **Create API** allows corpora to be created programmatically, up to the
+* The **Create Corpus API** allows corpora to be created programmatically, up to the
 limit defined for the account. 
-* The **Reset API** deletes all data from a corpus, without
+* The **Reset Corpus API** deletes all data from a corpus, without
 deleting its definition.
-* The **Delete API** expunges both the data in the corpus and 
+* The **Delete Corpus API** expunges both the data in the corpus and 
 its definition.
 
 

www/docs/api-reference/admin-apis/corpus/compute-corpus-size.md

@@ -7,7 +7,7 @@ sidebar_label: Compute Corpus Size API Definition
 import {Config} from '@site/docs/definitions.md';
 import {vars} from '@site/static/variables.json';
 
-The Compute Corpus Size endpoint lets you view the amount of quota consumed 
+The Compute Corpus Size API lets you view the amount of quota consumed 
 by a corpus. This capability is useful for administrators to track and monitor 
 the amount of usage for specific corpora. For example, you manage multiple 
 tenants and determine that a user consumed too much quota and you might decide 

www/docs/api-reference/admin-apis/corpus/list-documents.md

@@ -20,7 +20,7 @@ capabilities into their applications.
 :::tip
 
 Check out our [**interactive API Playground**](/docs/rest-api/list-documents) that lets you experiment with this 
-REST endpoint to manage your documents.
+REST endpoint to list your documents.
 
 :::
 
@@ -39,7 +39,7 @@ configure up to 1000.
 ### List Documents REST Endpoint Address
 
 <Config v="names.product"/> exposes a REST endpoint at the following URL
-to list the documents in a corpus:
+to list documents:
 <code>https://<Config v="domains.rest.admin"/>/v1/list-documents</code>
 
 The API Playground shows the full [List Documents](/docs/rest-api/list-documents) REST definition.

www/docs/api-reference/admin-apis/corpus/read-corpus.md

@@ -29,7 +29,7 @@ because of information returned by this endpoint.
 :::tip
 
 Check out our [**interactive API Playground**](/docs/rest-api/read-corpus) that lets you experiment with this 
-REST endpoint to manage your corpus details.
+REST endpoint to read your corpus details.
 
 :::
 
@@ -50,7 +50,7 @@ API keys with a specific corpus.
 ### Read Corpus REST Endpoint Address
 
 <Config v="names.product"/> exposes a REST endpoint at the following URL
-to read a corpus:
+to read information about the corpus:
 <code>https://<Config v="domains.rest.admin"/>/v1/read-corpus</code>
 
 The API Playground shows the full [Read Corpus](/docs/rest-api/read-corpus) REST definition.

www/docs/api-reference/admin-apis/corpus/update-corpus-enablement.md

@@ -33,7 +33,7 @@ to `true` or `false`.
 ### Update Corpus Enablement REST Endpoint Address
 
 <Config v="names.product"/> exposes a REST endpoint at the following URL
-to update the status of a corpus:
+to enable or disable a corpus:
 <code>https://<Config v="domains.rest.admin"/>/v1/update-corpus-enablement</code>
 
 The API Playground shows the full [Update Corpus Enablement](/docs/rest-api/update-corpus-enablement) REST definition.

www/docs/api-reference/admin-apis/create-corpus.md

@@ -1,6 +1,6 @@
 ---
 id: create-corpus
-title: Create Corpus
+title: Create Corpus API Definition
 sidebar_label: Create Corpus API Definition
 ---
 
@@ -10,7 +10,6 @@ import {vars} from '@site/static/variables.json';
 The Create Corpus API lets you create a corpus that contains specific 
 properties and attributes.
 
-
 :::tip
 
 Check out our [**API Playground**](/docs/rest-api/create-corpus) that lets you experiment with this REST endpoint 
@@ -23,9 +22,9 @@ to create corpora.
 When you create a `corpus` object, only the `name` and `description` fields are 
 mandatory.
 
-The response message returns a unique id, `corpus_id`, by which the corpus can
-be subsequently referenced. Note that the name needn't be unique within an
-account.
+The response message returns a unique id, `corpus_id`, by which the corpus 
+can be subsequently referenced. Note that the name needn't be unique 
+within an account.
 
 In order to reference metadata in [filter expressions](/docs/learn/metadata-search-filtering/filter-overview), the
 referenceable attributes must be declared at creation time in the **filter
@@ -62,7 +61,7 @@ values.
 ### Create Corpus REST Endpoint
 
 <Config v="names.product"/> exposes a REST endpoint at the following URL
-to ingest content into a corpus:
+to create a corpus:
 <code>https://<Config v="domains.rest.admin"/>/v1/create-corpus</code>
 
 The API Playground shows the full [Create Corpus](/docs/rest-api/create-corpus) REST definition.
@@ -74,4 +73,3 @@ You can find the full Create Corpus gRPC definition at [admin.proto](https://git
 The `CreateCorpusRequest` message contains a Corpus message with the name, 
 description, and other customization options. The `CreateCorpusResponse` 
 provides the response with the new Corpus ID and status.
-

www/docs/api-reference/admin-apis/delete-corpus.md

@@ -1,7 +1,7 @@
 ---
 id: delete-corpus
-title: Delete Corpus
-sidebar_label: API Definition
+title: Delete Corpus API Definition
+sidebar_label: Delete Corpus API Definition
 ---
 
 import {Config} from '@site/docs/definitions.md';
@@ -30,7 +30,7 @@ to delete corpora.
 ### Delete Corpus REST Endpoint
 
 <Config v="names.product"/> exposes a REST endpoint at the following URL
-to ingest content into a corpus:
+to delete a corpus:
 <code>https://<Config v="domains.rest.admin"/>/v1/delete-corpus</code>
 
 The API Playground shows the full [Delete Corpus](/docs/rest-api/delete-corpus) REST definition.

www/docs/api-reference/admin-apis/manage-users/manage-user.md

@@ -21,7 +21,7 @@ permissions.
 
 :::tip
 
-Check out our [interactive API Playground](/docs/rest-api/manage-user) that lets 
+Check out our [**interactive API Playground**](/docs/rest-api/manage-user) that lets 
 you experiment with this REST endpoint to manage users for your Vectara
 account.
 

www/docs/api-reference/admin-apis/reset-corpus.md

@@ -1,7 +1,7 @@
 ---
 id: reset-corpus
-title: Reset Corpus
-sidebar_label: API Definition
+title: Reset Corpus API Definition
+sidebar_label: Reset Corpus API Definition
 ---
 
 import {Config} from '@site/docs/definitions.md';
@@ -32,4 +32,4 @@ The API Playground shows the full [Delete Corpus](/docs/rest-api/delete-corpus)
 
 ## gRPC Example
 
-You can find the full Reset Corpus gRPC definition at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto).
+You can find the full Reset Corpus gRPC definition at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto).

www/docs/api-reference/api-keys/delete-api-key.md

@@ -24,10 +24,6 @@ you experiment with this REST endpoint to delete API keys from an account.
 
 :::
 
-## REST Example
-
-### Delete API Key Endpoint Address
-
 <Config v="names.product"/> exposes a REST endpoint at the following URL
 to delete API keys:
 <code>https://<Config v="domains.rest.indexing"/>/v1/delete-api-key</code>

www/docs/api-reference/api-keys/enable-api-key.md

@@ -26,7 +26,6 @@ Check out our [**interactive API Playground**](/docs/rest-api/enable-api-key) th
 you experiment with this REST endpoint to enable and disable API keys.
 
 :::
-
 ## REST Example
 
 ### Enable API Key REST Endpoint Address
@@ -39,4 +38,4 @@ The API Playground shows the full [Enable API Key](/docs/rest-api/enable-api-key
 
 ## gRPC Example
 
-You can find the full Enable API Key gRPC definition at [admin_apikey.proto](https://github.com/vectara/protos/blob/main/admin_apikey.proto).
+You can find the full Enable API Key gRPC definition at [admin_apikey.proto](https://github.com/vectara/protos/blob/main/admin_apikey.proto).

www/docs/api-reference/overview.md

@@ -12,9 +12,9 @@ import {Config} from '@site/docs/definitions.md';
 
 Everything in <Config v="names.product"/> is driven by APIs. This section serves 
 as a roadmap to understanding and using our [gRPC APIs](/docs/api-reference/protobuf-definitions) and 
-[REST APIs](/docs/api-reference/rest) for indexing, searching, and administrative tasks.
-Before getting into more details, we 
-recommend that you have a basic understanding of API concepts.
+[REST APIs](/docs/api-reference/rest) for [indexing](/docs/learn/select-ideal-indexing-api), [querying](/docs/api-reference/search-apis/search), and administrative tasks 
+such as [managing user access](/docs/api-reference/admin-apis/manage-users/manage-user) and [corpora](/docs/api-reference/admin-apis/admin). Before getting into more 
+details, we recommend that you have a basic understanding of API concepts.
 
 ## :star2: Ready to Dive In? Check Out Our API Playground! :star2:
 
@@ -31,18 +31,13 @@ and other key concepts:
 
 * **gRPC APIs:** Understand the basics of gRPC (Remote Procedure Call) such as 
   the advantages with performance, code generation, and how it uses Protocol 
-  Buffers (**.proto** files) for schema defnitions.
-
-  You can [download the `.proto` files](https://github.com/vectara/protos/tree/main) directly from Github. 
-  For example, [`serving.proto`](https://github.com/vectara/protos/blob/main/serving.proto) 
+  Buffers (**.proto** files) for schema defnitions. You can [download the `.proto` files](https://github.com/vectara/protos/tree/main) directly 
+  from Github. For example, [`serving.proto`](https://github.com/vectara/protos/blob/main/serving.proto) 
 provides the message definitions for running queries.
-
 * **RESTful APIs:** Understand the principles of Representational State Transfer 
   (REST) and why it's commonly used in web services. Make sure to also 
-  understand how it differs from gRPC.
-
-  For example, review the [Java example](/docs/getting-started-samples/RestIndex.java) for our Standard Indexing API. 
-
+  understand how it differs from gRPC. For example, review the [Java example](/docs/getting-started-samples/RestIndex.java) for our 
+  Standard Indexing API. 
 * **HTTP Methods:** Become familar with HTTP methods like GET, POST, PUT, and DELETE.
 * **gRPC Methods:** Become familar with gRPC methods like server streaming, client
   streaming, and bidirectional streaming.
@@ -65,9 +60,9 @@ APIs and some organizations still struggle with using HTTP/2.0 due to firewalls.
 
 ### REST API
 If you'd like more details about how to use our REST APIs, including details on
-our OpenAPI specification and services, a good place to start is the [REST](rest)
+our OpenAPI specification and services, a good place to start is the [REST APIs](rest)
 page.
 
 ### gRPC API
 If you'd like more details about how to use our gRPC APIs, including details on
-how to generate strongly typed clients, see our [gRPC](protobuf-definitions) page.
+how to generate strongly typed clients, see our [gRPC APIs](protobuf-definitions) page.

www/docs/api-reference/search-apis/batched-queries.md

@@ -1,7 +1,7 @@
 ---
 id: batched-queries
-title: Batching Multiple Queries
-sidebar_label: Batched Queries
+title: Batch Multiple Queries
+sidebar_label: Batch Multiple Queries
 ---
 
 import Tabs from '@theme/Tabs';
@@ -11,8 +11,10 @@ import {vars} from '@site/static/variables.json';
 
 Some applications may be designed to be powered by different queries in
 different parts of the UI.  In order to decrease the number of network round
-trips (and thereby the net latency), you may want to issue those multiple
-queries to the system with a single API call.
+trips (and thereby the net latency), you may want to batch those multiple
+queries with a single API call.
+
+## Query Array in a Request
 
 This pattern can be done in <Config v="names.product"/> by sending an array of
 queries in a single request, as in:
@@ -38,11 +40,10 @@ separate query for billing purposes.
 
 :::
 
-## Responses
+## Batched Query Responses
 
-When you a query <Config v="names.product"/>, you get back an array of results.
-This array is to assist in using
-[Batched Query](/docs/api-reference/search-apis/batched-queries.md), 
+When you query <Config v="names.product"/>, you get back an array of results.
+This array is to assist in using batched queries. 
 
 ```jsx
 {

www/docs/api-reference/search-apis/interpreting-responses/highlighting.md

@@ -1,14 +1,14 @@
 ---
 id: highlighting
 title: Highlighting and Snippet Extraction
-sidebar_label: Highlighting
+sidebar_label: Highlighting and Snippet Extraction
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import {Config} from '@site/docs/definitions.md';
 
-When you receive search results from <Config v="names.product"/>, alongside the
+When you receive query results from <Config v="names.product"/>, alongside the
 result, you'll receive a values for `section` and `offset`.  For example:
 
 ```json showLineNumbers

www/docs/api-reference/search-apis/interpreting-responses/metadata.md

@@ -1,7 +1,7 @@
 ---
 id: metadata
 title: Reading Metadata
-sidebar_label: Metadata
+sidebar_label: Reading Metadata
 ---
 
 import Tabs from '@theme/Tabs';

www/docs/api-reference/search-apis/interpreting-responses/scores.md

@@ -1,19 +1,17 @@
 ---
 id: interpreting-scores
 title: Interpreting Scores
-sidebar_label: Scores
+sidebar_label: Interpreting Scores
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import {Config} from '@site/docs/definitions.md';
 
-## Overview
-
-Like all search systems, <Config v="names.product"/> scores documents on how
-relevant they are to the query.  And like all search systems, <Config v="names.product"/>
-it's important to understand the scoring system and how it changes based on
-the controls and query parameters you've provided.
+Like all information retrieval systems, <Config v="names.product"/> scores documents on how
+relevant they are to the query. It's important to understand the scoring 
+system and how it changes based on the controls and query parameters you have 
+provided.
 
 Out of the box scores in <Config v="names.product"/>:
 1. Can be either positive or negative
@@ -26,8 +24,13 @@ Out of the box scores in <Config v="names.product"/>:
 See the sections below on "standard" and "reranked" results for details on
 how they differ and how to use them best.
 
-Note that <Config v="names.product"/> provides an important control that can affect scores:
-[custom dimensions](/docs/learn/semantic-search/add-custom-dimensions), which allow you to boost or bury results based on metadata.
+:::note
+
+Vectara provides an important control that can affect scores:
+[**custom dimensions**](/docs/learn/semantic-search/add-custom-dimensions), which allow you to boost 
+or bury results based on metadata.
+
+:::
 
 
 ## Comparison With Keyword Systems
@@ -84,7 +87,7 @@ results as no longer very relevant.  However, as a general rule, scores less
 than 0.1 tend to be of low quality and can typically be safely removed/ignored.
 
 ## Reranked Results Response
-Scores from <Config v="names.product"/> after reranking will be scored on a
+Scores from <Config v="names.product"/> after [reranking](/docs/api-reference/search-apis/reranking) are scored on a
 scale from -infinity to +infinity.  Internally, the numbers returned from the
 reranker are derived from a logarithmic scoring system, which means that in
 practice, scores much higher than 10 or much lower than -10 should be rare.
@@ -93,6 +96,4 @@ As with standard results, there's no hard rule around when to cut off results,
 but scores above around 2.5 or so tend to be pretty good, though we advise
 users to test with their own data and some sample queries.
 
-Note that the reranker is *currently* English-only, so if you get very low
-scores, you might want to check that your content is in English and disable
-the reranker where that isn't the case.
+

www/docs/api-reference/search-apis/search.md

@@ -11,8 +11,8 @@ import {vars} from '@site/static/variables.json';
 
 The Query API lets you perform a query while defining its parameters 
 that specify the query text, pagination details, metadata filters, and other 
-settings that enable application builders to tailor their queries to specific 
-use cases.
+search settings that enable application builders to tailor their queries to 
+specific use cases.
 
 After you index data into one or more corpora, you can run queries 
 and display the results. This page provides a detailed reference for how