docs: Rate limits, Applications, schema management and API docs

docs/api-documentation.md

@@ -4,12 +4,23 @@ products: all
 
 # API documentation
 
-Airbyte has two sets of APIs which are intended for different uses. The table below outlines their descriptions, use cases, availability and status.
-
-|                    | **Airbyte API**                                                                                                                                                                                                                                                        | **Configuration API**                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Description**    | Airbyte API is a reliable, easy-to-use interface for programmatically controlling the Airbyte platform. With full support from the Airbyte team.                                                                                                                       | The Config API is an internal Airbyte API that is designed for communications between different Airbyte components.                                                                                                                                                                                                                                                                                                                                              |
-| **Use Cases**      | Enables users to control Airbyte programmatically and use with Orchestration tools (ex: Airflow) <br /><br /> Exists for Airbyte users to write applications against. <br /><br /> Enables [Powered by Airbyte](https://airbyte.com/embed-airbyte-connectors-with-api) | Enables Airbyte Engineering team to configure Airbyte                                                                                                                                                                                                                                                                                                                                                                                                            |
-| **Intended users** | Airbyte OSS, Cloud & Self-Hosted Enterprise                                                                                                                                                                                                                            | Airbyte Engineering Team                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| **Status**         | Available to all Airbyte users (OSS, Cloud, Self-Hosted Enterprise). Learn more on our [blog](https://airbyte.com/blog/airbyte-api). <br /><br /> Full support from the Airbyte team.                                                                                  | Airbyte does NOT have active commitments to support this API long-term. Users utilize the Config API, at their own risk. <br /><br /> This API is utilized internally by the Airbyte Engineering team and may be modified in the future if the need arises. <br /><br /> Modifications by the Airbyte Engineering team could create breaking changes and OSS users would need to update their code to catch up to any backwards incompatible changes in the API. |
-| **Documentation**  | [Available here](https://api.airbyte.com)                                                                                                                                                                                                                              | [Available here](https://airbyte-public-api-docs.s3.us-east-2.amazonaws.com/rapidoc-api-docs.html)                                                                                                                                                                                                                                                                                                                                                               |
+The Airbyte API provides a way for developers to programmatically interact with Airbyte. It is available for all Airbyte products: Airbyte OSS, Cloud & Self-Hosted Enterprise. 
+
+Our API is a reliable, easy-to-use interface for programmatically controlling the Airbyte platform. It can be extended to: 
+
+- Enable users to control Airbyte programmatically and use with Orchestration tools (ex: Airflow)
+- Enable [Powered by Airbyte](https://reference.airbyte.com/reference/powered-by-airbyte)
+
+## Configuring API Access
+
+View our documentation [here](./using-airbyte/configuring-api-access.md) to learn how to start using the Airbyte API.             
+
+## Using the Airbyte API
+Navigate to our full API documentation to learn how to retrieve your access token, make API requests, and manage resources like sources, destinations, and workspaces. 
+
+Our full API documentation is located here: [api.airbyte.com](https://reference.airbyte.com/reference/getting-started).
+
+## Configuration API (Deprecated)
+The configuration API is now deprecated and no longer supported. It is an internal API that is designed for communications between different Airbyte components ratther than.
+
+Users utilize the Config API at their own risk. This API is utilized internally by the Airbyte Engineering team and may be modified in the future if the need arises. 

docs/cloud/managing-airbyte-cloud/review-connection-status.md

@@ -57,18 +57,25 @@ The Status page offers users visibility into the recent history of your syncs. F
 
 ### Resolving Connection Errors
 
-If the most recent sync failed, you'll see the error message that will help to diagnose whether the failure is due to a configuration or system error. 
+If the most recent sync failed, you'll see the error message that will help to diagnose next steps. If a sync starts to fail, it will automatically be disabled after multiple consecutive failures or several consecutive days of failure.
 
-Configuration errors are highlighted in red. If the failure is due to a configuration error, Airbyte recommends navigating to the related source or destination to re-test and save before attempting another sync.
+#### Rate-Limited Syncs
+If a source is being rate-limited by Airbyte trying to extract data, an informational message will be displayed. This can occure more frequently when Airbyte is attempting to pull a large amount of data. If available from the source, Airbyte will also show a countdown to when the sync will attempt to start syncing again. 
+
+![Rate Limited Status](./assets/rate_limited.png)
+
+Airbyte will not continue attempting to sync until the rate limit is lifted. The Active Streams section will indicate which specific streams have been rate limited. The sync will automatically start attempting to sync again once the rate limit has lifted. 
+
+#### Configuration Errors
+Configuration errors are shown in red. If the failure is due to a configuration error, Airbyte recommends navigating to the related source or destination to re-test and save before attempting another sync.
 
 ![Configuration Error](./assets/configuration-error.png)
 
-All other errors are highlighted in yellow. These can range from transient errors to warnings from the source (e.g. rate limits). These types of errors usually resolve themselves without any action required. 
+#### System Errors
+Sync errors can also be shown in yellow. These can range from transient errors to warnings from the source (e.g. rate limits). These types of errors usually resolve themselves without any action required. 
 
 ![Warning Error](./assets/warning-error.png)
 
-If a sync starts to fail, it will automatically be disabled after multiple consecutive failures or several consecutive days of failure.
-
 ### Major Version Upgrades (Cloud only)
 If a new major version of the connector has been released in Cloud, you will also see a banner on this page indicating the cutoff date for the version upgrade. Airbyte recommends upgrading before the cutoff date to ensure your data continues syncing. If you do not upgrade before the cutoff date, Airbyte will automatically disable your connection.
 

docs/using-airbyte/configuring-api-access.md

@@ -0,0 +1,115 @@
+---
+products: all
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Configuring API Access
+
+The Airbyte API enables you to programmatically interact with Airbyte: create sources, destinations, run syncs, list workspaces, and much more.
+
+Access to the API is controlled through application keys. Applications keys are tied to individual users and their respective permissions. 
+
+# Prerequisites
+<Tabs groupId="cloud-hosted">
+  <TabItem value="cloud" label="Cloud">
+   Access to a Cloud workspace.
+
+  </TabItem>
+  <TabItem value="self-managed" label="Self-Managed">
+    A deployment of Airbyte Self-Managed that exposes the `airbyte-server` service. 
+  </TabItem>
+</Tabs>
+
+## Step 1: Create an Application
+
+While logged into the Airbyte UI, go to Settings -> Account -> Applications. Click the button "Create an application". 
+
+![Create an Application](./assets/applications-ui.png)
+
+Name your application for easy identification.
+
+![Name Application](./assets/applications-create.png)
+
+
+A `client_id` and `client_secret` will be automatically generated. The `client_secret` can be exposed by clicking on the icon next to the secret.
+
+![Get Application Client and Secret](./assets/applications-client-secret.png)
+
+## Step 2: Obtain an Access Token
+
+Once the `client_secret` is exposed, you can use the button in the UI to get an access token to do a quick test. 
+
+You can also use the `client_id` and `client_secret` to retrive an access token using the [Get an Access Token endpoint](https://reference.airbyte.com/reference/createaccesstoken).
+
+
+<Tabs groupId="cloud-hosted">
+  <TabItem value="cloud" label="Cloud">
+
+    ```yml
+    POST https://api.airbyte.com/api/v1/applications/token
+    ```
+
+    Ensure the following JSON Body is attached to the request, populated with your `client_id` and `client_secret`:
+
+    ```yaml
+    { 
+      "client_id": "", 
+      "client_secret": "" 
+      }
+    ```
+
+  </TabItem>
+  <TabItem value="self-managed" label="Self-Managed">
+    Self-Managed users should replace `<YOUR_WEBAPP_URL>` below with the URL used to access the Airbyte UI
+
+    ```yml
+    POST <YOUR_WEBAPP_URL>/api/v1/applications/token
+    ```
+
+    Ensure the following JSON Body is attached to the request, populated with your `client_id` and `client_secret`:
+
+    ```yaml
+    { 
+      "client_id": "", 
+      "client_secret": "" 
+      }
+    ```
+  </TabItem>
+</Tabs>
+
+The API response should provide an `access_token`, which is a Bearer Token valid for 3 minutes. It can be used to make requests to the API. Once your `access_token` expires, you must make a new request to the `applications/token` endpoint to get a new token.
+
+:::tip
+Access tokens are short-lived (3 minutes) so we recommend fetching a new token before each request. The Terraform Provider/SDKs properly handle this for you if you initialize the Provider/SDK with the Client Credentials grant type using your Application's `client_id` and `client_secret`.
+:::
+
+## Step 3: Operate Airbyte via API
+
+You may now make requests to any endpoint documented in our [Airbyte API Reference](https://reference.airbyte.com). For example, you may use the [List workspaces endpoint](https://reference.airbyte.com/reference/listworkspaces) to verify the list of workspaces in your organization. Ensure to include your `access_token` as a `Bearer Token` in your request.:
+
+```yaml
+GET <YOUR_WEBAPP_URL>/api/public/v1/workspaces
+```
+
+Expect a response like the following:
+
+```json
+{
+  "data": [
+    {
+      "workspaceId": "b5367aab-9d68-4fea-800f-0000000000",
+      "name": "Finance Team",
+      "dataResidency": "auto"
+    },
+    {
+      "workspaceId": "b5367aab-9d68-4fea-800f-0000000001",
+      "name": "Analytics Team",
+      "dataResidency": "auto"
+    }
+  ]
+}
+```
+
+To go further, you may use our [Python](https://github.com/airbytehq/airbyte-api-python-sdk) and [Java](https://github.com/airbytehq/airbyte-api-java-sdk) SDKs to make API requests directly in code, or our [Terraform Provider](https://registry.terraform.io/providers/airbytehq/airbyte/latest) (which uses the Airbyte API) to declare your Airbyte configuration as infrastructure.