seedPass/docs/docs/content/01-getting-started/02-api_reference.md

# 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.
- `POST /api/v1/entry` – Create a new entry of any supported type.
- `PUT /api/v1/entry/{id}` – Modify an existing entry.
- `PUT /api/v1/config/{key}` – Update a configuration value.
- `POST /api/v1/secret-mode` – Enable or disable Secret Mode and set the clipboard delay.
- `POST /api/v1/entry/{id}/archive` – Archive an entry.
- `POST /api/v1/entry/{id}/unarchive` – Unarchive an entry.
- `GET /api/v1/config/{key}` – Return the value for a configuration key.
- `GET /api/v1/fingerprint` – List available seed fingerprints.
- `POST /api/v1/fingerprint` – Add a new seed fingerprint.
- `DELETE /api/v1/fingerprint/{fp}` – Remove a fingerprint.
- `POST /api/v1/fingerprint/select` – Switch the active fingerprint.
- `GET /api/v1/totp/export` – Export all TOTP entries as JSON.
- `GET /api/v1/totp` – Return current TOTP codes and remaining time.
- `GET /api/v1/stats` – Return statistics about the active seed profile.
- `GET /api/v1/parent-seed` – Reveal the parent seed or save it with `?file=`.
- `GET /api/v1/nostr/pubkey` – Fetch the Nostr public key for the active seed.
- `POST /api/v1/checksum/verify` – Verify the checksum of the running script.
- `POST /api/v1/checksum/update` – Update the stored script checksum.
- `POST /api/v1/change-password` – Change the master password for the active profile.
- `POST /api/v1/vault/import` – Import a vault backup from a file or path.
- `POST /api/v1/vault/export` – Export the vault and download the encrypted file.
- `POST /api/v1/vault/backup-parent-seed` – Save an encrypted backup of the parent seed.
- `POST /api/v1/vault/lock` – Lock the vault and clear sensitive data from memory.
- `GET /api/v1/relays` – List configured Nostr relays.
- `POST /api/v1/relays` – Add a relay URL.
- `DELETE /api/v1/relays/{idx}` – Remove the relay at the given index (1‑based).
- `POST /api/v1/relays/reset` – Reset the relay list to defaults.
- `POST /api/v1/shutdown` – Stop the server gracefully.

**Security Warning:** Accessing `/api/v1/parent-seed` exposes your master seed in plain text. Use it only from a trusted environment.

## 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"
```

### Creating an Entry

`POST /api/v1/entry` accepts a JSON body with at least a `label` field. Set
`type` (or `kind`) to choose the entry variant (`password`, `totp`, `ssh`, `pgp`,
`nostr`, `seed`, `key_value`, or `managed_account`). Additional fields vary by
type:

- **password** – `length`, optional `username`, `url` and `notes`
- **totp** – `secret` or `index`, optional `period`, `digits`, `notes`, `archived`
- **ssh/nostr/seed/managed_account** – `index`, optional `notes`, `archived`
- **pgp** – `index`, `key_type`, `user_id`, optional `notes`, `archived`
- **key_value** – `value`, optional `notes`

Example creating a TOTP entry:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/entry \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"type": "totp", "label": "Email", "secret": "JBSW..."}'
```

### Updating an Entry

Use `PUT /api/v1/entry/{id}` to change fields such as `label`, `username`,
`url`, `notes`, `period`, `digits` or `value` depending on the entry type.

```bash
curl -X PUT http://127.0.0.1:8000/api/v1/entry/1 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"username": "alice"}'
```

### Updating Configuration

Send a JSON body containing a `value` field to `PUT /api/v1/config/{key}`:

```bash
curl -X PUT http://127.0.0.1:8000/api/v1/config/inactivity_timeout \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"value": 300}'
```

### Toggling Secret Mode

Send both `enabled` and `delay` values to `/api/v1/secret-mode`:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/secret-mode \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"enabled": true, "delay": 20}'
```

### Switching Fingerprints

Change the active seed profile via `POST /api/v1/fingerprint/select`:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/fingerprint/select \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
    -d '{"fingerprint": "abc123"}'
```

### Exporting the Vault

Download an encrypted vault backup via `POST /api/v1/vault/export`:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/vault/export \
     -H "Authorization: Bearer <token>" \
     -o backup.json
```

### Importing a Vault

Restore a backup with `POST /api/v1/vault/import`. Use `-F` to upload a file:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/vault/import \
     -H "Authorization: Bearer <token>" \
     -F file=@backup.json
```

### Locking the Vault

Clear sensitive data from memory using `/api/v1/vault/lock`:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/vault/lock \
     -H "Authorization: Bearer <token>"
```

### Backing Up the Parent Seed

Trigger an encrypted seed backup with `/api/v1/vault/backup-parent-seed`:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/vault/backup-parent-seed \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"path": "seed_backup.enc"}'
```

### Retrieving Vault Statistics

Get profile stats such as entry counts with `GET /api/v1/stats`:

```bash
curl -H "Authorization: Bearer <token>" \
     http://127.0.0.1:8000/api/v1/stats
```

### Changing the Master Password

Update the vault password via `POST /api/v1/change-password`:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/change-password \
     -H "Authorization: Bearer <token>"
```

### Verifying the Script Checksum

Check that the running script matches the stored checksum:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/checksum/verify \
     -H "Authorization: Bearer <token>"
```

### Updating the Script Checksum

Regenerate the stored checksum using `/api/v1/checksum/update`:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/checksum/update \
     -H "Authorization: Bearer <token>"
```

### Managing Relays

List, add, or remove Nostr relays:

```bash
# list
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8000/api/v1/relays

# add
curl -X POST http://127.0.0.1:8000/api/v1/relays \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"url": "wss://relay.example.com"}'

# remove first relay
curl -X DELETE http://127.0.0.1:8000/api/v1/relays/1 \
     -H "Authorization: Bearer <token>"

# reset to defaults
curl -X POST http://127.0.0.1:8000/api/v1/relays/reset \
     -H "Authorization: Bearer <token>"
```

### 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.