OverviewAuthenticationEndpointsWebhooksErrorsRate LimitsSDKsChangelog

API Reference

The Resona API provides programmatic access to autonomic state computation, coherence monitoring, intervention logging, and trend analysis. All endpoints return JSON and follow REST conventions.

Base URL: https://api.resona.health/v1

Authentication

All API requests require a Bearer token in the Authorization header. Keys are issued per-organization and can be rotated via the dashboard. Use the principle of least privilege.

curl -X GET https://api.resona.health/v1/state?user_id=usr_8x2k \
  -H "Authorization: Bearer rk_live_abc123..." \
  -H "Content-Type: application/json"

Keys follow the format rk_live_ (production) or rk_test_ (sandbox). Rotate keys regularly.

Endpoints

POST/v1/ingest

Ingest physiological signals from a data source.

POST /v1/ingest
Content-Type: application/json

{
  "source": "apple_health",
  "user_id": "usr_8x2k",
  "timestamp": "2026-02-09T10:30:00Z",
  "metrics": {
    "hrv_ms": 48.2,
    "rhr_bpm": 62,
    "skin_temp_c": 33.1,
    "sleep_hours": 7.2,
    "steps": 4200
  }
}
GET/v1/state?user_id={id}&range={days}d

Retrieve computed autonomic state for a user.

GET /v1/state?user_id=usr_8x2k&range=7d

// Response 200
{
  "user_id": "usr_8x2k",
  "coherence_score": 72,
  "corridor_status": "in",
  "stress_index": 0.31,
  "readiness": 0.84,
  "confidence": 0.91,
  "parasympathetic": 0.67,
  "sympathetic": 0.33,
  "computed_at": "2026-02-09T10:35:00Z"
}
POST/v1/interventions/log

Log an intervention event.

POST /v1/interventions/log
Content-Type: application/json

{
  "user_id": "usr_8x2k",
  "type": "breathing",
  "duration_sec": 180,
  "notes": "Box breathing after elevated stress alert"
}
GET/v1/trends?user_id={id}&range={days}d

Retrieve trend data over time.

GET /v1/trends?user_id=usr_8x2k&range=30d

// Response 200
{
  "user_id": "usr_8x2k",
  "range": "30d",
  "corridor_adherence_pct": 73.2,
  "series": {
    "coherence": [68, 71, 65, 74, ...],
    "stress": [0.42, 0.38, 0.51, 0.29, ...],
    "recovery": [0.61, 0.67, 0.58, 0.72, ...]
  }
}
POST/v1/alerts/subscribe

Subscribe to threshold-based alerts.

POST /v1/alerts/subscribe
Content-Type: application/json

{
  "user_id": "usr_8x2k",
  "channels": ["webhook"],
  "thresholds": {
    "coherence_below": 40,
    "stress_above": 0.8
  }
}

Webhooks

Subscribe to real-time events. All webhooks include a signature header for verification.

autonomic.alert

Fired when a metric crosses a configured threshold.

corridor.exit

User coherence has dropped below the golden corridor (< 0.618).

corridor.return

User coherence has returned to corridor range.

Signature verification header:

X-Resona-Signature: sha256=abc123...
X-Resona-Timestamp: 1707500100

Errors

All errors return a consistent JSON structure with a machine-readable code and human-readable message.

{
  "error": {
    "code": 401,
    "message": "Invalid or expired API key",
    "request_id": "req_x9f2k..."
  }
}
CodeDescription
400Bad request -- invalid parameters
401Unauthorized -- missing or invalid key
403Forbidden -- insufficient permissions
429Rate limited -- back off and retry
500Internal server error

Rate Limits

Soft limits are enforced per API key. If you exceed them, requests will return 429 with a Retry-After header.

Default limit

60 req/min

Burst allowance

10 req/sec

Use exponential backoff on 429 responses. Contact us for higher limits.

SDKs

Official SDKs are in development. For now, any HTTP client works.

JavaScript/TS

Coming soon

Python

Coming soon

Swift

Planned

Changelog

2026-02-09

v1.0.0-preview

Initial developer preview. Ingest, state, trends, interventions, alerts.

2026-01-15

v0.9.0

Internal alpha. Core state model and corridor gating.