Initial commit

starter-docs/endpoints.md

@@ -0,0 +1,229 @@
+# Cashumints.space API – Endpoints
+
+Base path:
+
+/v1
+
+All endpoints are read‑only unless stated otherwise.
+All timestamps are ISO‑8601 UTC.
+All mint‑specific endpoints accept either a mint ID or a mint URL.
+
+---
+
+## Resolution Rules
+
+Endpoints support:
+- `/v1/mints/{mint_id}`
+- `/v1/mints/by-url?url=...`
+
+The API resolves URLs to the canonical mint_id internally.
+
+---
+
+## Single Mint – Core
+
+GET /v1/mints/{mint_id}
+GET /v1/mints/by-url?url=
+
+Returns:
+- mint_id
+- canonical_url
+- urls[]
+- name
+- icon_url
+- status
+- offline_since
+- last_success_at
+- last_failure_at
+- uptime_24h
+- uptime_7d
+- uptime_30d
+- incidents_7d
+- incidents_30d
+- trust_score
+- trust_level
+
+---
+
+## Mint URLs
+
+GET /v1/mints/{mint_id}/urls
+GET /v1/mints/by-url/urls?url=
+
+Returns:
+- canonical_url
+- urls[]:
+  - url
+  - type (clearnet | tor | mirror)
+  - active
+
+---
+
+## Metadata (NUT‑06)
+
+GET /v1/mints/{mint_id}/metadata
+GET /v1/mints/by-url/metadata?url=
+
+Returns:
+- name
+- pubkey
+- version
+- description
+- description_long
+- contact
+- motd
+- icon_url
+- urls
+- tos_url
+- nuts
+- server_time
+- last_fetched_at
+
+---
+
+GET /v1/mints/{mint_id}/metadata/history
+GET /v1/mints/by-url/metadata/history?url=
+
+Returns:
+- fetched_at
+- change_type
+- diff
+- version
+
+---
+
+## Status (Lightweight)
+
+GET /v1/mints/{mint_id}/status
+GET /v1/mints/by-url/status?url=
+
+Returns:
+- status
+- offline_since
+- last_checked_at
+- current_rtt_ms
+
+---
+
+## Uptime & Reliability
+
+GET /v1/mints/{mint_id}/uptime
+GET /v1/mints/by-url/uptime?url=
+
+Query:
+- window=24h | 7d | 30d
+
+Returns:
+- uptime_pct
+- downtime_seconds
+- avg_rtt_ms
+- p95_rtt_ms
+- total_checks
+- ok_checks
+
+---
+
+GET /v1/mints/{mint_id}/uptime/timeseries
+GET /v1/mints/by-url/uptime/timeseries?url=
+
+Query:
+- window=24h | 7d | 30d
+- bucket=5m | 15m | 1h
+
+Returns:
+- timestamp
+- state
+- ok
+- rtt_ms
+
+---
+
+## Incidents
+
+GET /v1/mints/{mint_id}/incidents
+GET /v1/mints/by-url/incidents?url=
+
+Returns:
+- started_at
+- resolved_at
+- duration_seconds
+- severity
+
+---
+
+## Trust
+
+GET /v1/mints/{mint_id}/trust
+GET /v1/mints/by-url/trust?url=
+
+Returns:
+- score_total
+- score_level
+- breakdown
+- computed_at
+
+---
+
+## Reviews (Nostr)
+
+GET /v1/mints/{mint_id}/reviews
+GET /v1/mints/by-url/reviews?url=
+
+Returns:
+- event_id
+- pubkey
+- created_at
+- rating
+- content
+
+---
+
+## Popularity
+
+GET /v1/mints/{mint_id}/views
+GET /v1/mints/by-url/views?url=
+
+Returns:
+- views_24h
+- views_7d
+- views_30d
+- unique_sessions_30d
+- view_velocity
+
+---
+
+## Derived Features
+
+GET /v1/mints/{mint_id}/features
+GET /v1/mints/by-url/features?url=
+
+Returns:
+- supported_nuts
+- supports_bolt11
+- min_amount
+- max_amount
+- has_tor_endpoint
+- has_multiple_urls
+- feature_completeness_score
+
+---
+
+## Submission
+
+POST /v1/mints/submit
+
+Body:
+- mint_url
+
+Returns:
+- mint_id
+- status
+- message
+
+---
+
+## Health & Stats
+
+GET /v1/health
+GET /v1/stats
+