From 1aa9447df2d641da5ffe58bc3e0c3475d2f4c02b Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Wed, 9 Jul 2025 11:45:47 -0400
Subject: [PATCH] Add REST API documentation

---
 README.md             |  2 +-
 docs/README.md        |  2 +-
 docs/api_reference.md | 50 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 docs/api_reference.md

diff --git a/README.md b/README.md
index 108af09..9719589 100644
--- a/README.md
+++ b/README.md
@@ -217,7 +217,7 @@ You can also use the new Typer-based CLI:
 ```bash
 seedpass --help
 ```
-For details see [docs/advanced_cli.md](docs/advanced_cli.md).
+For a full list of commands see [docs/advanced_cli.md](docs/advanced_cli.md). The REST API is described in [docs/api_reference.md](docs/api_reference.md).
 
 ### Running the Application
 
diff --git a/docs/README.md b/docs/README.md
index 000d23d..eb149ff 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,4 +16,4 @@ Code: 123456
 
 ## CLI and API Reference
 
-See [advanced_cli.md](advanced_cli.md) for a list of command examples and instructions on running the local API. When starting the API, set `SEEDPASS_CORS_ORIGINS` if you need to allow requests from specific web origins.
+See [advanced_cli.md](advanced_cli.md) for a list of command examples. Detailed information about the REST API is available in [api_reference.md](api_reference.md). When starting the API, set `SEEDPASS_CORS_ORIGINS` if you need to allow requests from specific web origins.
diff --git a/docs/api_reference.md b/docs/api_reference.md
new file mode 100644
index 0000000..5302d51
--- /dev/null
+++ b/docs/api_reference.md
@@ -0,0 +1,50 @@
+# SeedPass REST API Reference
+
+This guide covers how to start the SeedPass API, authenticate requests, and interact with the available endpoints.
+
+## Starting the API
+
+Run `seedpass api start` from your terminal. The command prints a one‑time token used for authentication:
+
+```bash
+$ seedpass api start
+API token: abcdef1234567890
+```
+
+Keep this token secret. Every request must include it in the `Authorization` header using the `Bearer` scheme.
+
+## Endpoints
+
+- `GET /api/v1/entry?query=<text>` – Search entries matching a query.
+- `GET /api/v1/entry/{id}` – Retrieve a single entry by its index.
+- `GET /api/v1/config/{key}` – Return the value for a configuration key.
+- `GET /api/v1/fingerprint` – List available seed fingerprints.
+- `GET /api/v1/nostr/pubkey` – Fetch the Nostr public key for the active seed.
+- `POST /api/v1/shutdown` – Stop the server gracefully.
+
+## Example Requests
+
+Send requests with the token in the header:
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+     "http://127.0.0.1:8000/api/v1/entry?query=email"
+```
+
+### Enabling CORS
+
+Cross‑origin requests are disabled by default. Set `SEEDPASS_CORS_ORIGINS` to a comma‑separated list of allowed origins before starting the API:
+
+```bash
+SEEDPASS_CORS_ORIGINS=http://localhost:3000 seedpass api start
+```
+
+Browsers can then call the API from the specified origins, for example using JavaScript:
+
+```javascript
+fetch('http://127.0.0.1:8000/api/v1/entry?query=email', {
+  headers: { Authorization: 'Bearer <token>' }
+});
+```
+
+Without CORS enabled, only same‑origin or command‑line tools like `curl` can access the API.