Developer Guide

This guide will help you understand how to claim your applications, work with the REST APIs, and (if eligible) ingest biosignals using the SWIP SDK.

Quick Start

1. Sign in – Visit /auth and authenticate via Google or GitHub
2. Register or claim your application in /developer
   • Register when your app is new to SWIP
   • Claim when a SWIP integration already created an entry and you need ownership
3. Generate an analytics API key – Keys are shown once; copy them into your secret manager
4. Use the analytics API – Read session, biosignal, and emotion data for the apps you own
5. (Optional) Request ingestion access – If you need to push biosignals, submit an ingestion verification request

---

Analytics API (Read-Only)

Base URL: https://swip.synheart.io/api/v1

All requests require the following header:

x-api-key: YOUR_ANALYTICS_KEY

Available Endpoints

Endpoint	Method	Description	Key Query Params
/apps	GET	List your claimed apps with summary metrics	limit (1-100), category
/app_sessions	GET	Paginated SWIP sessions for owned apps	app_id, limit
/app_sessions	DELETE	Delete all sessions for a user/device combination	user_id, device_id (both required)
/app_biosignals	GET	Biosignals for a session	app_session_id (required)
/emotions	GET	Emotion events for a session/biosignal	app_session_id or app_biosignal_id
/public/stats	GET	Global anonymized statistics	(none)

Sample: List Sessions

curl -X GET "https://swip.synheart.io/api/v1/app_sessions?app_id=com.synheart.focus&limit=25" \
  -H "x-api-key: ${SWIP_ANALYTICS_KEY}"

Sample: Delete Sessions

Delete all sessions for a specific user and device combination:

curl -X DELETE "https://swip.synheart.io/api/v1/app_sessions?user_id=USER_UUID&device_id=DEVICE_UUID" \
  -H "x-api-key: ${SWIP_ANALYTICS_KEY}"

Response:

{
  "success": true,
  "message": "Deleted 15 sessions for user/device combination",
  "deleted_count": 15
}

Emotion Labels

Label	Meaning
calm	Relaxed state with low physiological stress
stressed	Elevated stress markers (HR, HRV)
focused	Sustained attention / flow response

---

Ingestion API (Verified Partners Only)

Base URL: https://swip.synheart.io/api/v1

Endpoint	Payload Summary	Notes
POST /apps	{ app_id, app_name, ... }	Upserts app metadata
POST /app_sessions	{ app_session_id, started_at, ended_at, ... }	Duration is auto-computed
POST /app_biosignals	[ { app_biosignal_id, timestamp, metrics... }, ... ]	Up to 100 signals per request
POST /emotions	[ { app_biosignal_id, swip_score, dominant_emotion, ... }, ... ]	Must reference existing biosignals

Requests must include the ingestion key:

x-api-key: YOUR_INGESTION_KEY

Ingestion Workflow

1. Collect biometrics using Synheart Wear adapters
2. Feed raw samples into the SWIP SDK for pre-processing, scoring, and batching
3. The SDK validates payloads and sends them to the ingestion endpoints
4. Successful ingestion updates the leaderboard, analytics, and developer dashboards

---

Data Model

Entity	Highlights
App	External identifier (app_id), ownership, metadata
AppSession	Tracks a single usage event; holds start/end timestamps, device ID, opt-in flags
AppBiosignal	Timestamped biosignal payload (HR, HRV, SpO₂, temperature, accelerometer, etc.)
Emotion	SWIP score + subscores derived from biosignals
ApiKey	Stores hashed API keys for analytics or ingestion

SWIP Score = phys_subscore (0-60) + emo_subscore (0-40) → range 0-100

---

Rate Limits

Endpoint Group	Limit	Window
/apps, /app_sessions	120	60 seconds
/app_biosignals, /emotions	60	60 seconds

Response Headers

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Error Response Format

{
  "success": false,
  "error": "Unauthorized: Invalid or missing authentication",
  "message": "This endpoint requires x-api-key header"
}

---

Best Practices

• Generate separate API keys per environment (dev/staging/prod)
• Cache analytics responses whenever possible (apps list, leaderboard snapshots)
• Validate ingestion payloads locally using SWIP SDK helpers before streaming
• Revoke unused keys in the developer portal to reduce attack surface
• Log request_id values returned by the API for faster support

---

Code Examples

Node.js

const fetch = require('node-fetch');

const API_KEY = process.env.SWIP_API_KEY;
const BASE_URL = 'https://swip.synheart.io/api/v1';

async function listApps(limit = 10) {
  const res = await fetch(`${BASE_URL}/apps?limit=${limit}`, {
    headers: { 'x-api-key': API_KEY },
  });
  const data = await res.json();
  if (!data.success) throw new Error(data.error);
  return data.apps;
}

Python

import os
import requests

API_KEY = os.getenv("SWIP_API_KEY")
BASE_URL = "https://swip.synheart.io/api/v1"

def list_sessions(app_id):
    response = requests.get(
        f"{BASE_URL}/app_sessions",
        params={"app_id": app_id, "limit": 20},
        headers={"x-api-key": API_KEY},
    )
    data = response.json()
    if not data.get("success"):
        raise RuntimeError(data.get("error"))
    return data["sessions"]

cURL

# List claimed apps
curl -X GET 'https://swip.synheart.io/api/v1/apps?limit=10' \
  -H 'x-api-key: swip_key_your_key_here'

# Fetch biosignals for a session
curl -X GET 'https://swip.synheart.io/api/v1/app_biosignals?app_session_id=SESSION_UUID' \
  -H 'x-api-key: swip_key_your_key_here'

---

Support & Resources

• Dashboard: swip.synheart.io
• Developer Portal: swip.synheart.io/developer
• API Health Check: GET /api/health
• Email: support@swip.synheart.io
• Issues: GitHub Issues
• Terms: /docs/terms • Privacy: /docs/privacy