/

API Documentation

v1
SpecAPI

PulseESM API Reference

API-first Experience Sampling Method platform. 56 endpoints across 11 categories.

Base URL: https://pulseesm-production.up.railway.appJSON responsesBearer token authOpenAPI 3.0
Machine-readable spec:
pulseesm.com/openapi.json

Quick Start Guide

Complete flow: account creation → study setup → data collection → export. Designed for AI agents and scripts.

1. Create an account

Sign up with your email, then verify it to get your API key.

# Sign up
curl -X POST https://pulseesm-production.up.railway.app/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123",
    "name": "Dr. Smith"
  }'

# Check your email and click the verification link.
# Then get your API key:
curl -X POST https://pulseesm-production.up.railway.app/v1/auth/regenerate-key \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'
# Save the returned api_key — it won't be shown again.

2. Create a study (or use a template)

Create from scratch or use a pre-built template.

# Option A: From template (recommended for quick start)
curl -X POST https://pulseesm-production.up.railway.app/v1/studies/from-template/daily-mood-diary \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Mood Study"}'

# Option B: From scratch
curl -X POST https://pulseesm-production.up.railway.app/v1/studies \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Work Engagement Study",
    "schedule": {
      "type": "signal-contingent",
      "signals_per_day": 5,
      "window": {"start": "09:00", "end": "18:00"},
      "duration_days": 10
    }
  }'

3. Add survey items (skip if using template)

Add questions: likert, slider, single_choice, multi_choice, text, number.

curl -X POST https://pulseesm-production.up.railway.app/v1/studies/1/items \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "type": "likert",
        "text": "How engaged are you right now?",
        "scale": 7,
        "anchors": {"1": "Not at all", "7": "Completely"}
      },
      {
        "type": "slider",
        "text": "Stress level?",
        "min": 0, "max": 100,
        "labels": {"0": "None", "100": "Maximum"}
      },
      {
        "type": "single_choice",
        "text": "Current activity?",
        "options": ["Working", "Meeting", "Break", "Other"]
      }
    ]
  }'

4. Enroll participants

Invite participants by email. PulseESM creates accounts for them.

curl -X POST https://pulseesm-production.up.railway.app/v1/studies/1/participants \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ]
  }'

5. Deploy the study

Activates the study and generates notification signals for all participants.

curl -X POST https://pulseesm-production.up.railway.app/v1/studies/1/deploy \
  -H "Authorization: Bearer sk-your-api-key"

# Response:
# {
#   "message": "Study deployed successfully",
#   "signals_generated": 150,
#   "participants_count": 3
# }

6. Monitor & export data

Check analytics and download response data anytime.

# View real-time analytics
curl https://pulseesm-production.up.railway.app/v1/studies/1/analytics \
  -H "Authorization: Bearer sk-your-api-key"

# Export as CSV with within-person centering
curl "https://pulseesm-production.up.railway.app/v1/studies/1/responses?format=csv&centering=person" \
  -H "Authorization: Bearer sk-your-api-key" \
  -o study_data.csv

# Export as JSON
curl "https://pulseesm-production.up.railway.app/v1/studies/1/responses?format=json" \
  -H "Authorization: Bearer sk-your-api-key"