Add REST API documentation

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
 

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.

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.