tellscoin/doc/api.md

API Reference

Base Behavior

• Base URL: same origin as UI host.
• UI route:
  • GET / returns the dashboard HTML shell.
• API route namespace:
  • All API endpoints are under /api/....
• Cache behavior:
  • Responses under /api/ and /static/ include no-store cache headers.

Authentication Model

• Login endpoint sets a session value on success.
• Protected endpoints require Depends(require_auth).
• Session cookie behavior:
  • same_site=lax
  • max age: 8 hours
  • secure flag controlled by SESSION_COOKIE_SECURE

Related references:

• Configuration: doc/environment.md
• Auth implementation: app/auth.py

Error Contract

• 401 for authentication failures.
• 400 for missing required node configuration values.
• 422 for request validation and unsupported chart window values.
• 502 for RPC or SSH operation failures.
• Error shape for handled exceptions:
  • { "detail": "<message>" }

Endpoint Contracts

Health and Session

Method	Path	Auth	Description
GET	/api/health	No	Returns service liveness: { "ok": true }.
GET	/api/auth/me	No	Returns current authentication state and username if authenticated.
POST	/api/auth/login	No	Validates credentials and creates session.
POST	/api/auth/logout	Yes	Clears session.

POST /api/auth/login request body:

{
  "username": "admin",
  "password": "secret"
}

Node Settings

Method	Path	Auth	Description
GET	/api/settings	Yes	Returns persisted node connection and control settings.
PUT	/api/settings	Yes	Validates and persists node settings.

PUT /api/settings request body fields:

• rpc_url string
• rpc_username string
• rpc_password string
• rpc_wallet string
• config_path string
• ssh_host string
• ssh_port integer 1..65535
• ssh_username string
• ssh_password string
• ssh_key_path string
• bitcoin_binary string

All string fields are trimmed before persistence.

Dashboard

Method	Path	Auth	Description
GET	/api/dashboard/summary	Yes	Returns chain, network, mempool, mining, uptime, optional wallet data, and updated_at.
GET	/api/dashboard/history	Yes	Returns metric history for query-param window and limit.
GET	/api/dashboard/history/{window}	Yes	Same as above with window as a path parameter.

Supported window values:

• 5m
• 30m
• 2h
• 6h
• all

limit is clamped server-side to [1, 20000].

RPC Explorer

Method	Path	Auth	Description
POST	/api/rpc/call	Yes	Executes a JSON-RPC method with params and optional wallet override.
GET	/api/rpc/commands	Yes	Calls node help and returns parsed method catalog.
GET	/api/rpc/help/{method_name}	Yes	Returns detailed help output for one method.

POST /api/rpc/call request body:

{
  "method": "getblockchaininfo",
  "params": [],
  "wallet": null
}

Node Actions

Method	Path	Auth	Description
POST	/api/actions/stop	Yes	Calls RPC stop.
POST	/api/actions/start	Yes	Runs SSH start command built from persisted settings.
POST	/api/actions/restart	Yes	Attempts RPC stop then runs SSH start command.

Action responses include action metadata and remote execution payload when SSH is involved.

Operational Notes

• Startup and restart require:
  • valid SSH connectivity
  • config_path
  • SSH user credentials or key access
• When running in Docker, rpc_url should usually target host.docker.internal if the node is on the Docker host.

See doc/build-and-deploy.md for Docker network details.