Document Async APIs

docs/api/async-apis.mdx

@@ -0,0 +1,123 @@
+---
+sidebar_position: 8
+title: Asynchronous APIs
+---
+
+# Asynchronous APIs
+
+Some API operations can take a while to complete. For these APIs, Permit will run them in the background after the request
+is complete. When an asynchronous API is called, you will receive a `202 Accepted` response, with a unique `task_id` in
+response body. You can use this ID to check the status of the task, and to retrieve a result when the task is completed
+successfully, or an error if the task failed.
+
+Some operations offer both an asynchronous and a synchronous call, for backwards compatibility. The default behavior is
+to use the synchronous call, but you can request an asynchronous call by setting the `?async=true` URL parameter.
+
+## Calling an asynchronous API
+The `Copy Environment` API is an example of an asynchronous-optional API. To call this API, you can use the following
+curl command:
+
+```shell
+$ curl -v "https://api.permit.io/v2/projects/{project_id}/envs/{environment_id}/copy" \
+ -d '
+ {
+   "target_env": {
+     "name": "Copied Env",
+      "key": "copied"
+    }
+ }'
+> POST /v2/projects/{project_id}/envs/{environment_id}/copy HTTP/1.1
+>
+{
+  "target_env": {
+        "name": "Copied Env",
+        "key": "copied"
+  }
+}
+< HTTP/1.1 200 OK
+<
+{
+  "key": "copied",
+  "id": "{copied_environment_id}",
+  "organization_id": "{organization_id",
+  "project_id": "{project_id}",
+  "created_at": "2023-07-30T15:56:21+00:00",
+  "updated_at": "2023-07-30T15:56:21+00:00",
+  "name": "Copied Env",
+  "description": null,
+  "jwks": null,
+  "settings": null
+}
+```
+
+To call the same API asynchronously, you can use the following curl command:
+```shell
+$ curl -v "https://api.permit.io/v2/projects/{project_id}/envs/{environment_id}/copy?async=true" \
+ -d '
+ {
+   "target_env": {
+     "name": "Copied Env",
+      "key": "copied"
+    }
+ }'
+> POST /v2/projects/{project_id}/envs/{environment_id}/copy HTTP/1.1
+>
+{
+  "target_env": {
+    "name": "Copied Env",
+    "key": "copied"
+  }
+}
+< HTTP/1.1 202 Accepted
+< Content-Type: application/json
+< Location: /v2/tasks/copy_environment/{task_id}
+<
+{
+  "operation_name": "copy_environment",
+  "task_id": "{task_id}"
+}
+```
+
+## Checking the status of a task
+
+To check the status of a task, you can use the following curl command:
+
+```shell
+$ curl -v "https://api.permit.io/v2/tasks/copy_environment/{task_id}"
+> GET /v2/tasks/{task_id} HTTP/1.1
+>
+< HTTP/1.1 200 OK
+< Content-Type: application/json
+{
+    "id": "{task_id}",
+    "operation_name": "copy_environment",
+    "status": "finished",
+    "created_at": "2024-05-05T18:06:09+00:00",
+    "started_at": "2024-05-05T18:06:09+00:00",
+    "finished_at": "2024-05-05T18:06:09+00:00",
+    "organization_id": "{organization_id}"
+}
+```
+
+To retrieve the result of the task, or its error, use the `/result` endpoint:
+
+```shell
+$ curl -v "https://api.permit.io/v2/tasks/copy_environment/{task_id}/result"
+> GET /v2/tasks/{task_id} HTTP/1.1
+>
+< HTTP/1.1 200 OK
+< Content-Type: application/json
+{
+  "key": "copied",
+  "id": "{copied_environment_id}",
+  "organization_id": "{organization_id",
+  "project_id": "{project_id}",
+  "created_at": "2023-07-30T15:56:21+00:00",
+  "updated_at": "2023-07-30T15:56:21+00:00",
+  "name": "Copied Env",
+  "description": null,
+  "jwks": null,
+  "settings": null
+}
+```
+