# Cashumints.space – Admin Endpoints

This document defines the **admin-only API surface** of Cashumints.space.

These endpoints exist to:

* curate mint data safely
* correct discovery or URL issues
* resolve identity conflicts
* force recomputation when rules change
* debug the background system

Admin endpoints **never fabricate reality**. They annotate, correct routing, or trigger recomputation, but they do not delete historical data.

---

## General Rules

* Base path: `/admin`
* Authentication: `ADMIN_API_KEY` (static header)
* All admin actions are **audited**
* No admin endpoint deletes raw data
* Every mutation writes to the admin audit log

Audit log fields:

* admin_id
* action
* target
* before_state
* after_state
* timestamp

---

## POST /admin/mints

### Purpose

Manually add a mint to the system.

Used for:

* trusted bootstrap
* known operators
* recovery when auto-discovery fails

### Request body

```
{
  "mint_url": "https://mint.example",
  "notes": "optional internal notes"
}
```

### Logic

1. Normalize the URL
2. Check if URL already exists in `mint_urls`
3. If exists:

   * return existing mint_id
4. If not:

   * create new mint record
   * status = `unknown`
   * discovered_from = `manual`
   * create mint_url entry (active)
5. Enqueue immediate probe job

### Response

```
{
  "mint_id": "uuid",
  "status": "unknown",
  "message": "Mint added and scheduled for probing"
}
```

---

## POST /admin/mints/{mint_id}/urls

### Purpose

Manually attach an additional URL (clearnet, Tor, mirror) to an existing mint.

### Request body

```
{
  "url": "http://example.onion",
  "type": "tor",
  "active": true
}
```

### Logic

1. Normalize URL
2. Ensure URL is not linked to another mint
3. Create mint_urls entry
4. Mark source = `admin`
5. Enqueue probe for new URL

### Rules

* URLs are never deleted
* If duplicate URL exists, return 409

---

## POST /admin/mints/merge

### Purpose

Merge two mints that represent the same operator.

### Request body

```
{
  "source_mint_id": "uuid",
  "target_mint_id": "uuid",
  "reason": "Same pubkey, different URLs"
}
```

### Logic

1. Validate both mint IDs exist
2. Ensure source != target
3. Create merge record
4. Reassign all related data:

   * mint_urls
   * probes
   * metadata history
   * reviews
   * rollups
5. Mark source mint as `merged`
6. Target mint becomes canonical

### Rules

* No data is deleted
* Merge is reversible

---

## POST /admin/mints/split

### Purpose

Undo a previous mint merge.

### Request body

```
{
  "merge_id": "uuid"
}
```

### Logic

1. Load merge record
2. Restore original mint records
3. Reassign data back to original mint
4. Mark merge record as reverted

### Rules

* Only one split per merge
* Full restoration required

---

## POST /admin/mints/{mint_id}/disable

### Purpose

Hide a mint from public listings without deleting it.

### Logic

1. Set mint.visibility = `hidden`
2. Mint continues to be probed
3. Mint remains accessible by direct ID or URL

### Use cases

* scam submissions
* spam mints
* broken test instances

---

## POST /admin/mints/{mint_id}/enable

### Purpose

Re-enable a previously hidden mint.

### Logic

1. Set mint.visibility = `public`
2. No other state changes

---

## POST /admin/mints/{mint_id}/metadata/refresh

### Purpose

Force metadata fetch, bypassing the hourly limit.

### Logic

1. Enqueue metadata fetch job
2. Ignore METADATA_FETCH_INTERVAL
3. Metadata still validated normally

### Rules

* Does not fabricate metadata
* Failure does not erase existing metadata

---

## POST /admin/mints/{mint_id}/trust/recompute

### Purpose

Force trust score recomputation.

### Logic

1. Enqueue trust recompute job
2. Uses current rollups, reviews, metadata
3. Stores new score and breakdown

### Use cases

* scoring logic changes
* review moderation
* metadata correction

---

## GET /admin/jobs

### Purpose

Inspect the background job queue.

### Returns

```
[
  {
    "job_id": "uuid",
    "type": "probe_mint",
    "status": "pending",
    "run_at": "timestamp",
    "attempts": 2,
    "last_error": null
  }
]
```

### Rules

* Read-only
* No mutation

---

## GET /admin/system/metrics

### Purpose

High-level system health view.

### Returns

* total_mints
* online_mints
* offline_mints
* probes_last_minute
* failed_probes_last_minute
* job_backlog
* oldest_job_age_seconds
* database_size_mb
* worker_heartbeat

Used for operations and debugging.

---

## POST /admin/mints/{mint_id}/status/reset

### Purpose

Clear a stuck mint state caused by transient infrastructure issues.

### Logic

1. Reset consecutive_failures to 0
2. Clear offline_since
3. Do NOT change historical probes
4. Enqueue immediate probe

### Rules

* Does not fabricate uptime
* Next probe determines real status

---

## Final Admin Rule

Admins may correct **structure and routing**, but never rewrite **history or truth**.

If an action cannot be explained in the audit log, it does not belong in the admin API.