quixio · tbedford · Nov 7, 2023 · Oct 31, 2023 · Nov 2, 2023 · Nov 2, 2023
diff --git a/.github/workflows/build-commit-subfolder.yaml b/.github/workflows/build-commit-subfolder.yaml
@@ -148,7 +148,7 @@ jobs:
 
     # use our own GitHub Action to bring in library readme files
     - name: Quix Samples readme.md importer
-      uses: quixio/LibraryToMKDocsReadmeMergeAction@v2.13
+      uses: quixio/LibraryToMKDocsReadmeMergeAction@v2.16
       id: readme_importer
       with:
         LIBRARY_REPO_PATH: "samples"

diff --git a/.github/workflows/sync-build-deploy.yaml b/.github/workflows/sync-build-deploy.yaml
@@ -151,7 +151,7 @@ jobs:
 
       # use our own GitHub Action to bring in library readme files
       - name: Quix Samples readme.md importer
-        uses: quixio/LibraryToMKDocsReadmeMergeAction@v2.13
+        uses: quixio/LibraryToMKDocsReadmeMergeAction@v2.16
         id: readme_importer
         with:
           LIBRARY_REPO_PATH: "samples"

diff --git a/BEST-PRACTICE.md b/BEST-PRACTICE.md
@@ -68,7 +68,7 @@ As mentioned before, tutorials not only serve to inform, but to provide a learni
 
 As tutorials tend to be longer-form material, Quix uses the approach of splitting the tutorials up into *parts*. This enables the reader to attempt a part, leave it to one side should they so wish, and then return to continue with the tutorial when time permits. To help the tutorial be manageable, each part is further divided into steps. Steps are numbered to provide an additional source of reference, and make working through the procedure easier to track. 
 
-The Quix technical writing team attempts to keep the structure of each tutorial consistent, so that the layout for readers feels familiar. An example of this structure can be found in the [Sentiment Analysis tutorial](https://docs.quix.io/platform/tutorials/sentiment-analysis/index.html). Writers should always try to follow this structure consistently. 
+The Quix technical writing team attempts to keep the structure of each tutorial consistent, so that the layout for readers feels familiar. An example of this structure can be found in the [Sentiment Analysis tutorial](https://docs.quix.io/docs/tutorials/sentiment-analysis/index.html). Writers should always try to follow this structure consistently. 
 
 Note this particular tutorial also includes optional parts. This is done to keep the main tutorial length reasonable - the longer the tutorial, the less likely the reader is to complete it, as they can get lost in the myriad steps and configurations. By keeping things as simple as possible, and providing optional parts as self-contained addendum, things are kept much more manageable. 
 

diff --git a/docs/apis/api-references.md b/docs/apis/api-references.md
diff --git a/docs/apis/http-requests.md → docs/apis/portal-api/http-requests.md b/docs/apis/http-requests.md → docs/apis/portal-api/http-requests.md
@@ -4,13 +4,13 @@ How you send HTTP requests REST APIs varies depending on the client or language
 
 ## Sign requests using your PAT
 
-Make sure you accompany each request to the API with an `Authorization` header using your [Personal Access Token (PAT)](../platform/how-to/personal-access-token-pat.md) as a bearer token, as follows:
+Make sure you accompany each request to the API with an `Authorization` header using your Personal Access Token (PAT) as a bearer token, as follows:
 
 ``` http
 Authorization: bearer <token>
 ```
 
-Replace `<token>` with your [Personal Access Token (PAT)](../platform/how-to/personal-access-token-pat.md). 
+Replace `<token>` with your Personal Access Token (PAT). 
 
 For example, if you’re using Curl on the command line, you can set the header using the `-H` flag:
 
@@ -24,7 +24,7 @@ If you fail to send a valid Authorization header, the API will respond with a `4
 
 APIs are available on a per-environment basis (with the exception of the Portal API), so the endpoint URL is based on your environment ID. 
 
-Read the documentation on [how to obtain your environment ID](../platform/how-to/get-environment-id.md).
+Read the documentation on how to obtain your environment ID.
 
 The API endpoint URL has the following format:
 

diff --git a/docs/apis/images/apis-tokens.png → docs/apis/portal-api/images/apis-tokens.png b/docs/apis/images/apis-tokens.png → docs/apis/portal-api/images/apis-tokens.png
diff --git a/docs/apis/portal-api/index.md → docs/apis/portal-api/overview.md b/docs/apis/portal-api/index.md → docs/apis/portal-api/overview.md
@@ -1,4 +1,4 @@
-# Portal API
+# Overview
 
 The Portal API gives access to the Portal interface enabling you to programmatically control projects, environments, applications, and deployments.
 
diff --git a/docs/apis/portal-api/setup.md b/docs/apis/portal-api/setup.md
@@ -0,0 +1,109 @@
+# Setup
+
+To use the APIs you'll typically need the following:
+
+1. [Sign up to Quix](https://portal.platform.quix.ai/self-sign-up).
+
+2. Obtain a Personal Access Token - you need this to authenticate requests.
+
+3. Get your environment ID - you need this for request URLs.
+
+4. View the API reference documentation.
+
+5. If you intend to use WebSockets, and the API supports it, you'll need to install SignalR.
+
+Each of these is described in the following sections.
+
+## Project settings
+
+Useful information can also be found in the settings panels for your environment:
+
+1. Click `Settings` in the bottom left corner of the Quix portal.
+
+2. From `Project settings` select the environment you are working with.
+
+3. Click `APIs and tokens`.
+
+You are now presented with a very useful panel. From here you have useful links to items such as API documentation (rendered with Swagger), as well as your Personal Access Tokens (PATs):
+
+![APIs and tokens](./images/apis-tokens.png){width=80%}
+
+## Personal access token (PAT)
+
+Personal Access Tokens, or PATs, are bearer tokens that can be used to authenticate the various Quix APIs, such as the Portal API.
+
+To obtain a PAT, log in to Quix, and click on your profile icon in the top right corner, then click `Personal Access Tokens`. You can then generate a PAT with a lifetime suitable for your use case.
+
+Alternatively, log in to the Quix Portal, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
+
+In the `APIs and tokens` dialog, you can click `Personal Access Tokens` to generate PATs, or a Streaming Token for use with the Quix Streams client library.
+
+## Get environment ID
+
+When using APIs you’ll need to obtain an ID based on a specific environment. For example, endpoints for the [Query API](../../apis/query-api/overview.md) use a domain with the following pattern:
+
+    https://telemetry-query-${environment-id}.platform.quix.ai/
+
+The environment ID is a combination of your organization and environment names, converted to URL friendly values. 
+
+### Obtain your environment ID from the URL
+
+1.  Go to the [Portal home](https://portal.platform.quix.ai/){target=_blank}.
+
+2.  Locate the environment you’re interested in and open it.
+
+3.  At this point, take note of the URL. It will be in the form:
+
+    https://portal.platform.quix.ai/home?workspace={environment-id}
+
+### Obtain environment ID from settings
+
+You can also get the environment ID from Settings. Click `Settings` in the bottom-left corner of the portal, select the environment of interest. You can then copy the environment ID (previously known as the workspace ID) from the settings panel, as shown in the following screenshot:
+
+![Get environment ID from settings](../../images/get-environment-id/get-environment-id-settings.png){width=80%}
+
+### Example environment ID
+
+Given the following URL for the environment:
+
+```
+https://portal.platform.quix.ai/pipeline?workspace=joeengland-apitests-testing
+```
+
+The environment ID is:
+
+```
+joeengland-apitests-testing
+```
+
+The components of the environment ID are as follows:
+
+| joeengland | The name of the Quix account, known as the organization, in this case the personal account of Joe England |
+| apitests | The name of the project |
+| testing | The name of the environment | 
+
+Copy the value for `environment-id` and use it wherever you need an environment ID.
+
+!!! note
+
+    The `workspace=` parameter in the URL `https://portal.platform.quix.ai/home?workspace={environment-id}` is there for legacy reasons, and does in fact indicate an environment.
+
+## API reference documentation
+
+An OAS3 API reference guides are available for HTTP/REST APIs. These are rendered using [Swagger](https://swagger.io/){target=_blank}. 
+
+The URLs for the API references are specific to your environment, so you can easily test out API calls on your environment using the API reference. You'll need to get you environment ID. The exception to this is the Portal API, which is account-wide.
+
+| API | API reference URL (Swagger documentation)|
+|---|---|
+| Streaming Writer | https://writer-`<environment-id>`.platform.quix.ai/swagger |
+| Streaming Reader | No HTTP/REST interface - SignalR (WebSockets or Long Polling)|
+| Portal | https://portal-api.platform.quix.ai/swagger |
+| Query | https://telemetry-query-`<environment-id>`.platform.quix.ai/swagger |
+
+Replace `<environment-id>` with your environment ID.
+
+!!! tip
+
+    Once you access the API reference, you can select the version of the API you require from the `Select a definition` dropdown list.
+
diff --git a/docs/apis/prerequisites.md b/docs/apis/prerequisites.md
diff --git a/docs/apis/query-api/aggregate-tags.md b/docs/apis/query-api/aggregate-tags.md
@@ -2,12 +2,6 @@
 
 If you need to compare data across different values for a given tag, you’ll want to group results by that tag. You can do so using the `/parameters/data` endpoint.
 
-## Before you begin
-
-If you don’t already have any stream data in your environment, you can use a Source from the [Code Samples](../../platform/samples/samples.md) to provide suitable data.
-
-You'll need to obtain a [Personal Access Token](authenticate.md) to authenticate each request.
-
 ## Using the groupBy property
 
 You can supply a list of Tags in the `groupBy` array to aggregate results by. For example, you could group a set of Speed readings by the LapNumber they occurred on using something like:

diff --git a/docs/apis/query-api/aggregate-time.md b/docs/apis/query-api/aggregate-time.md
@@ -2,12 +2,6 @@
 
 You can downsample and upsample persisted data using the `/parameters/data` endpoint.
 
-## Before you begin
-
-If you don’t already have any Stream data in your environment, you can use a Source from the [Code Samples](../../platform/samples/samples.md) to provide suitable data.
-
-You'll need to obtain a [Personal Access Token](authenticate.md) to authenticate each request.
-
 ## Aggregating and interpolating
 
 The JSON payload can include a `groupByTime` property, an object with the following members:

diff --git a/docs/apis/query-api/authenticate.md b/docs/apis/query-api/authenticate.md
diff --git a/docs/apis/query-api/filter-tags.md b/docs/apis/query-api/filter-tags.md
@@ -2,12 +2,6 @@
 
 If you supply Tags with your parameter data, they will act as indexes, so they can be used to efficiently filter data.
 
-## Before you begin
-
-If you don’t already have any Stream data in your environment, you can use a Source from the [Code Samples](../../platform/samples/samples.md) to generate some.
-
-You'll need to obtain a [Personal Access Token](authenticate.md) to authenticate each request.
-
 ## Using tag filters
 
 When calling the `/parameters/data` endpoint, you can include a `tagFilters` property in your payload. This property references an array of objects, each with the following structure:

diff --git a/docs/apis/query-api/http-requests.md b/docs/apis/query-api/http-requests.md
@@ -0,0 +1,83 @@
+# HTTP requests
+
+How you send HTTP requests REST APIs varies depending on the client or language you’re using.
+
+## Sign requests using your PAT
+
+Make sure you accompany each request to the API with an `Authorization` header using your Personal Access Token (PAT) as a bearer token, as follows:
+
+``` http
+Authorization: bearer <token>
+```
+
+Replace `<token>` with your Personal Access Token (PAT). 
+
+For example, if you’re using Curl on the command line, you can set the header using the `-H` flag:
+
+``` shell
+curl -H "Authorization: bearer <token>" ...
+```
+
+If you fail to send a valid Authorization header, the API will respond with a `401 UNAUTHORIZED` status code.
+
+## Endpoint URLs
+
+APIs are available on a per-environment basis (with the exception of the Portal API), so the endpoint URL is based on your environment ID. 
+
+The API endpoint URL has the following format:
+
+```
+https://<api-name>-<environment-id>.platform.quix.ai/<action>
+```
+
+So, for example, the endpoint URL for the streaming writer might resemble the following:
+
+```
+https://writer-acme-weather.platform.quix.ai/<action>
+```
+
+The API is `writer`, and the environment ID is `acme-weather`.
+
+## HTTP method
+
+Endpoints in the API use HTTP methods such as `POST` and `PUT` methods. Ensure your HTTP client sends the correct request method.
+
+Using `curl`, you can specify the request method with the `-X <POST|PUT>` flag, for example:
+
+```bash
+curl -X PUT ...
+```
+
+## Payload
+
+For most methods, you’ll need to send a JSON object containing supported parameters. You’ll also need to set the appropriate content type for the payload you’re sending:
+
+```bash
+curl -H "Content-Type: application/json" ...
+```
+
+!!! warning
+
+	You **must** specify the content type of your payload. Failing to include this header will result in a `415 UNSUPPORTED MEDIA TYPE` status code.
+
+You can send data using the `curl` flag `-d`. This should be followed by either a string of JSON data, or a string starting with the *@* symbol, followed by a filename containing the JSON data.
+
+```bash
+curl -d '{"key": "value"}' ...
+curl -d "@data.json" ...
+```
+
+!!! tip
+
+	By default, `-d` will send a `POST` request, so `-X POST` becomes unnecessary.
+
+## Complete Curl example
+
+You should structure most of your requests to the API around this pattern:
+
+```bash
+curl -H "Authorization: bearer ${token}" \
+     -H "Content-Type: application/json" \
+     -d "@data.json" \
+     https://${api-name}-${environment-id}.platform.quix.ai/<action>
+```
diff --git a/docs/apis/query-api/images/apis-tokens.png b/docs/apis/query-api/images/apis-tokens.png
diff --git a/docs/apis/query-api/index.md → docs/apis/query-api/overview.md b/docs/apis/query-api/index.md → docs/apis/query-api/overview.md
@@ -1,10 +1,10 @@
-# Introduction
+# Overview
 
 The Query API enables you to fetch persisted data stored in the Quix platform. You can use it for exploring the platform, prototyping applications, or working with stored data in any language with HTTP capabilities.
 
 !!! note
 
-    The Query API is primarily designed for **testing purposes only**. For production storage of data, Quix recommends using one of the numerous [connectors](../../platform/connectors/index.md) to persist data in the database technology of your choice.
+    The Query API is primarily designed for **testing purposes only**. For production storage of data, Quix recommends using one of the numerous [connectors](../../connectors/index.md) to persist data in the database technology of your choice.
 
 ## Further documentation