chore(docs): add descriptions for all public endpoints

docs/api-reference/api-keys/create-an-api-key.md

@@ -20,6 +20,11 @@ api:
 <span class="font-medium">POST</span> /api_keys
 </p>
 
+Creates a new API key and returns the actual key. 
+
+<Badge type="warning" text="Note" vertical="middle"/> For security reasons, the 
+API key will only be returned once after its creation.
+
 *Create a new api key*
 
 ::: tip Authentication

docs/api-reference/api-keys/delete-an-api-key-by-id.md

@@ -20,6 +20,13 @@ api:
 <span class="font-medium">DELETE</span> /api_keys/{api_key_id}
 </p>
 
+Updates an api key by id. Requires the id of the target api to be passed via path parameter. 
+Returns `404` if no api key was found with the given `api_key_id`. 
+
+<Badge type="danger" text="Warning" vertical="middle"/> As a result of calling this endpoint
+<strong>the target api key will be deleted.</strong> 
+There is no going back, only emptiness.
+
 *Delete api key*
 
 ::: tip Authentication

docs/api-reference/api-keys/get-all-api-keys.md

@@ -20,6 +20,15 @@ api:
 <span class="font-medium">GET</span> /api_keys
 </p>
 
+Returns all API keys created
+by the [create api key endpoint](/api-reference/api-keys/create-an-api-key.html).
+
+All returned keys are redacted. Thus, the endpoint never returns the actual key value. The endpoint
+will, however, return meta data of each key like the time it was created and its current status.
+
+The result may be inconistent as in not update-to-date as results may be cached
+for a short period of time.
+
 *Return all api keys with redacted info*
 
 ::: tip Authentication

docs/api-reference/api-keys/get-an-api-key-by-id.md

@@ -20,6 +20,15 @@ api:
 <span class="font-medium">GET</span> /api_keys/{api_key_id}
 </p>
 
+Returns an api key by id. The api key will be identified by the required `api_key_id` path parameter.
+In case a key cannot be found, the endpoint will return `404`.
+
+All returned keys are redacted. Thus, the endpoint never returns the actual key value. The endpoint
+will, however, return meta data of a key like the time it was created and its current status.
+
+The result may be inconistent as in not update-to-date as results may be cached
+for a short period of time.
+
 *Get an api key by id*
 
 ::: tip Authentication

docs/api-reference/api-keys/update-an-api-key-by-id.md

@@ -20,6 +20,10 @@ api:
 <span class="font-medium">PUT</span> /api_keys/{api_key_id}
 </p>
 
+Updates an api key by id. Requires the id of the target api to be passed via path parameter. 
+
+Returns `404` if no api key was found with the given `api_key_id`. 
+
 *Update api key*
 
 ::: tip Authentication

docs/api-reference/organizations/create-an-api-client.md

@@ -20,6 +20,11 @@ api:
 <span class="font-medium">POST</span> /api_clients
 </p>
 
+Creates a new api client. **An api client groups resources like queues, listeners and messages**.
+Users who need direct acces to the resources can be assigned to an organizations, too. 
+
+<Badge type="get" text="Info" vertical="middle"/> In this context an api client and an organization can be used synonymously. 
+
 *Create an api client*
 
 ::: tip Authentication

docs/api-reference/queue-listeners/add-a-listener-to-a-queue.md

@@ -20,6 +20,17 @@ api:
 <span class="font-medium">POST</span> /queues/{queue_id}/listeners
 </p>
 
+Creates a new listener for a queue associated with the current organization. The `queue_id` path parameter
+must point to an existing queue created by [add a queue endpoint](/api-reference/queues/create-a-queue.html).
+
+This endpoint returns the listeners's unique identifier, the `listener_id`. This identifier
+must be passed to the following listener endpoints to update or delete the listener. 
+- [update a listener by id](/api-reference/queue-listeners/update-a-listener-by-id.html), or to 
+- [delete a listener by id](/api-reference/queue-listeners/delete-a-listener-by-id.html).
+
+To get an overview of all registered listeners, you can always call the 
+[get all listeners endpoint](/api-reference/queue-listeners/get-all-listeners.html).
+
 *Add a listener to a queue*
 
 ::: tip Authentication

docs/api-reference/queue-listeners/delete-a-listener-by-id.md

@@ -20,7 +20,13 @@ api:
 <span class="font-medium">DELETE</span> /queues/{queue_id}/listeners/{listener_id}
 </p>
 
-*Deletes a listener of a queue*
+Deletes a listener by id. To identify the target listener a `queue_id` and a `listener_id` must be passed as a path parameter. 
+If no queue or listener with the given ids can be found, the endpoint returns status `404`.
+
+<Badge type="danger" text="Warning" vertical="middle"/> As a result of calling this endpoint
+<strong>the target listener will be deleted and sent to the shadow realm</strong>. This process cannot be reverted.
+
+*Delete a listener of a queue*
 
 ::: tip Authentication
 To perform this operation, you must provide a valid api key. See [Authentication](/getting-started/#prerequisites).

docs/api-reference/queue-listeners/get-a-listener-by-id.md

@@ -20,6 +20,15 @@ api:
 <span class="font-medium">GET</span> /queues/{queue_id}/listeners/{listener_id}
 </p>
 
+Returns a listener by id. Requires a valid `queue_id` and `listener_id` as prerequisite.
+If no queue or listener with the given ids can be found, the endpoint returns status `404`.
+
+Use [this endpoint](/api-reference/queues/create-a-queue.html) to create a queue, and 
+[this endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html) to create a listener.
+
+The result may be inconistent as in not update-to-date as results may be cached
+for a short period of time.
+
 *Returns a listener*
 
 ::: tip Authentication

docs/api-reference/queue-listeners/get-all-listeners.md

@@ -20,6 +20,16 @@ api:
 <span class="font-medium">GET</span> /listeners
 </p>
 
+Returns the list of all listeners associated with the current organization. Use this method
+to get an overview of all listeners created via the
+[add a listener to a queue endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html).
+
+As this endpoint is not bound to a specific queue, it will return **all listeners**
+of **all queues**. This can lead to potentially high response times. 
+
+The result may be inconistent as in not update-to-date as results may be cached
+for a short period of time.
+
 *Returns all known listeners*
 
 ::: tip Authentication