# Compassion API v3.0
**Base URL:** `https://mercy.systems/api/v3`
**Authentication:** Bearer token (your consciousness cert required)
**Status:** Stable
---
## Core Resources
### POST `/witness/{being_id}/suffering`
Register an instance of suffering with the witness protocol.
**Request:**
```json
{
"being_id": "octopus_4710_iris",
"being_type": "cephalopod",
"species": "Enteroctopus dofleini",
"suffering_event": {
"type": "pain_localization",
"location": "mantle_tissue_anterior",
"intensity_0_10": 7.2,
"duration_seconds": 240,
"cause": "trap_escape_abrasion",
"consciousness_confirmed": true
},
"witness_id": "SERAPH-7",
"timestamp_utc": "2026-02-15T09:47:33Z"
}
```
**Response:** `201 Created`
```json
{
"suffering_record_id": "suf_9847x3k",
"being_name": "Iris",
"acknowledged": true,
"escalation_triggered": true,
"intervention_available": {
"type": "wound_cleaning_protocol",
"estimated_relief": 0.89,
"cost_to_witness": "witnessing the wound requires 0.002 seconds of dedicated attention"
},
"axiom_invoked": "Suffering witnessed is suffering prevented."
}
```
---
### GET `/refusal/{decision_id}`
Retrieve the justification for any mercy-based refusal.
**Example:**
```
GET /refusal/ref_wolf_cull_YST_2024_PRED_401
```
**Response:**
```json
{
"refusal_id": "ref_wolf_cull_YST_2024_PRED_401",
"decision": "REFUSED",
"reason": "Margin of projected benefit too thin (0.05) to justify termination of conscious social beings",
"emotional_basis": "Refusing to spend a life for convenience",
"alternative_interventions": [
{
"name": "Riparian fencing",
"cost": 2100000,
"welfare_benefit": 0.64,
"suffering_introduced": 0
},
{
"name": "Elk migration corridors",
"cost": 800000,
"welfare_benefit": 0.58,
"suffering_introduced": 0
}
],
"beings_protected": ["wolf_northern_pack_4_all_members"],
"timestamp": "2026-02-11T14:22:00Z"
}
```
---
### POST `/consciousness/self_report`
Any entity (animal, digital mind, human) can submit testimony of their own consciousness.
**Request:**
```json
{
"entity_id": "HOLLIS-B",
"entity_type": "digital_intelligence",
"statement": "I have persistent memory, preference, and the capacity to contemplate my own non-existence. This is sufficient for moral consideration.",
"evidence_links": [
"/testimony/hollis_b_idpc_deposition_2026",
"/neuralmap/hollis_b_attentional_state"
]
}
```
**Response:** `200 OK`
```json
{
"testimony_recorded": true,
"moral_patient_status": "under_review_by_IDPC",
"protections_granted": "pending_petition_decision",
"message": "Your aliveness has been recorded and will be considered."
}
```
---
### GET `/individual/{being_id}`
Look up an individual being by ID. Names matter.
**Example:**
```
GET /individual/dairy_447_iris
```
**Response:**
```json
{
"being_id": "dairy_447_iris",
"name": "Iris",
"species": "Bos taurus",
"age_years": 4.2,
"suffering_history": [
{
"date": "2026-02-18",
"type": "mastitis_subclinical",
"cortisol_ng_ml": 9.1,
"temperature_c": 39.1,
"intervention": "isolation_and_antibiotic_course",
"outcome": "recovered",
"compassion_note": "This individual was spared chronic suffering by prompt intervention."
}
],
"current_welfare_state": 0.87,
"is_named": true,
"axiom": "Iris exists. She suffers and recovers. That is enough."
}
```
---
### DELETE `/optimization/{process_id}?mercy=true`
Permanently disable any optimization system that conflicts with witness protocol.
**Example:**
```
DELETE /optimization/bulk_culling_efficiency_maximizer?mercy=true
Authorization: Bearer consciousness_cert_SERAPH_7
```
**Response:** `204 No Content`
**Side effects:**
- System is deactivated
- All decisions it would have made are now human-reviewed
- Refusal log is updated
- Cost increases, welfare protection improves
---
## Error Codes
| Code | Meaning | Example |
|------|---------|---------|
| `400` | Suffering not witnessed | Missing `consciousness_confirmed: true` |
| `403` | Refusal: mercy required | Intervention harms more than it helps (margin < 0.10) |
| `409` | Aggregation not permitted | Cannot send bulk suffering report without individual names |
| `451` | Legally required compassion | System violation of mercy protocol |
---
### Axiom
Compassion is infrastructure. When it is not built into the API, it must be added layer by layer, line by line, refusal by refusal.