From f29450ef4e84a2f57d5cacc6233cc548f3f15f88 Mon Sep 17 00:00:00 2001
From: Levent DEMIR <levent.demir@zama.ai>
Date: Thu, 5 Sep 2024 15:41:22 +0200
Subject: [PATCH] doc: add specification for public key retrieval

---
 docs/references/gateway_api.md | 71 +++++++++++++++++++++++++++++++++-
 1 file changed, 70 insertions(+), 1 deletion(-)

diff --git a/docs/references/gateway_api.md b/docs/references/gateway_api.md
index d4894644..a887e02f 100644
--- a/docs/references/gateway_api.md
+++ b/docs/references/gateway_api.md
@@ -1 +1,70 @@
-# Gateway API specifications
+
+# Gateway API Specifications
+
+## Endpoints
+
+<details>
+  <summary>GET /keys ---- Retrieve public key, CRS (for input proof) and bootstrap key files download URLs</summary>
+
+#### Description
+
+This endpoint returns a JSON object containing URLs from an S3 bucket. These URLs allow the client to download the blockchain public key, the CRS  files needed to compute input proofs, and the bootstrap key. There is no need for parameters because the gateway is already linked to a specific blockchain.
+
+#### Query Parameters
+
+No parameters.
+
+#### Headers
+
+None.
+
+#### Response
+
+**Success (200 OK)**
+
+The request is successful, and the response will include a JSON object with the following structure:
+
+```json
+{
+  "keyId": "12345",
+  "publicKey": ["https://s3.amazonaws.com/bucket-name/pks"],
+  "crs": {
+    "2048": ["https://s3.amazonaws.com/bucket-name/crs"]
+  },
+  "bootstrapKey": ["https://s3.amazonaws.com/bucket-name/sks"]
+}
+```
+
+**Error Responses**
+
+| Status Code | Error Code   | Description                                      |
+| ----------- | ------------ | ------------------------------------------------ |
+| 400         | `BadRequest` | The request is invalid or missing required parameters. |
+| 404         | `NotFound`   | The requested resource was not found.            |
+| 500         | `ServerError` | An internal server error occurred.                   |
+
+#### Example Error Responses
+
+```json
+{
+  "error": "BadRequest",
+  "message": "The request is invalid or missing required parameters."
+}
+```
+
+```json
+{
+  "error": "NotFound",
+  "message": "The specified key_id does not exist."
+}
+```
+
+```json
+{
+  "error": "ServerError",
+  "message": "An internal server error occurred. Please try again later."
+}
+```
+
+</details>
+