Developer Documentation

The Ready Mindset API

Embed the MQ Assessment, retrieve barrier profiles, manage the 90-Day Pathway, and integrate practitioner workflows into your healthcare, coaching, or HR platform.

v1.0.0 Base URL: api.myreadymindset.com/v1 REST · JSON
Getting Started

Overview

The Ready Mindset API gives your platform access to the MQ Assessment diagnostic, barrier scoring, the 90-Day Pathway, and practitioner management. All responses are JSON. Authentication uses API keys passed in the request header.

Base URL
All API requests should be made to https://api.myreadymindset.com/v1
Quick Start — Run Your First Request 
# Install dependencies
npm install axios

# Your first MQ Assessment session
const axios = require('axios');

const response = await axios.post(
  'https://api.myreadymindset.com/v1/assessment/sessions',
  {
    client_id: 'client_abc123',
    language: 'en'
  },
  {
    headers: {
      'Authorization': 'Bearer rm_live_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data.session_id); // sess_xyz789
Authentication

API Keys

All requests require an API key passed in the Authorization header as a Bearer token. Keys are prefixed with rm_live_ for production and rm_test_ for sandbox.

Keep your API key secret. Never expose it in client-side code, public repositories, or logs. Use environment variables.
Authentication Header 
Authorization: Bearer rm_live_xxxxxxxxxxxxxxxxxxxx
Environment Variables (Recommended) 
# .env
RM_API_KEY=rm_live_xxxxxxxxxxxxxxxxxxxx
RM_API_BASE=https://api.myreadymindset.com/v1

# Usage
headers: { 'Authorization': `Bearer ${process.env.RM_API_KEY}` }
Get your API key: Email hello@myreadymindset.com with your organisation name and intended use case. Sandbox keys are issued within 24 hours. Production keys after API review.
Errors & Rate Limits

Error Handling

The API uses standard HTTP status codes. All errors return a JSON object with a code, message, and optional detail field.

Error Response Format 
{
  "error": {
    "code":    "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "status":  401
  }
}
StatusCodeDescription
200okRequest succeeded
201createdResource created successfully
400bad_requestMissing or invalid parameters
401unauthorizedInvalid or missing API key
403forbiddenValid key but insufficient tier
404not_foundResource does not exist
429rate_limitedToo many requests — see limits below
500server_errorSomething went wrong on our end
Rate limits by tier: Free — 500 requests/month · Starter — 5,000/month · Starter+Pathway — 20,000/month · Enterprise — unlimited. Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.
Profile System

The 56-Profile Combinatorial Taxonomy

The MQ Assessment does not just return eight barrier scores. It identifies which of 56 distinct psychological profiles the respondent belongs to — each with a name, a super-cluster classification, and a specific tool sequence. Understanding this system is essential to building meaningful experiences for your users.

The formula: C(8,3) = 56. Eight barriers taken three at a time produce 56 unique three-barrier combinations. Each combination maps to a named profile with its own identity, internal pattern, and breakthrough insight.
How profiles are determined 
// The assessment returns scores for all 8 barriers
// The top 3 scores (sorted ascending by barrier index) form the profile key
// Example: top barriers are Inner Narrative (0), Capacity Gap (6), Isolation Trap (7)
// Key = "0,6,7" → profile: "The Lonely Overwhelmed Self-Doubter"

{
  "barriers": {
    "inner_narrative":    { "score": 22, "level": "high"   },
    "capacity_gap":       { "score": 19, "level": "high"   },
    "isolation_trap":     { "score": 17, "level": "high"   },
    // ... remaining 5 barriers
  },
  "profile_name":    "The Lonely Overwhelmed Self-Doubter",
  "super_cluster":   "The Lonely Struggler",
  "primary_barrier": "inner_narrative"
}
For product teams: Use profile_name to personalise your user experience — show the user their profile name as part of their results. Use super_cluster to segment users into nine groups for targeted content, notifications, or interventions. The profile names and super-cluster names are proprietary to The Ready Mindset — do not expose the full taxonomy to end users.
Example — personalising results in your product 
const result = await getAssessmentResults(sessionId);

// Show the user their profile
const profileName   = result.profile_name;   // "The Perfectionist Paralyzed"
const superCluster  = result.super_cluster;   // "The Perfectionist Paralyzed"
const primaryTool   = result.barriers[result.primary_barrier].tool;

// Display to user
showProfileCard({
  title:   profileName,
  cluster: superCluster,
  tool:    primaryTool,
  score:   result.mq_score
});

// Segment for analytics or notifications
trackUserSegment(userId, superCluster);

// Store for personalisation
await updateUserRecord(userId, {
  mq_profile:      profileName,
  mq_cluster:      superCluster,
  mq_score:        result.mq_score,
  primary_barrier: result.primary_barrier
});
Profile System

The 9 Super-Clusters

The 56 profiles collapse into 9 super-clusters for simplified segmentation, analytics, and intervention design. Each super-cluster has a primary tool entry point and a characteristic internal monologue. Use super-clusters when you need to group users for cohort analysis or targeted content.

Super-cluster reference 
{
  "super_clusters": [
    {
      "name":          "The Perfectionist Paralyzed",
      "core_dynamic":  "Internal shame + scarcity + overwhelm",
      "primary_tool":  "capacity_ladder",
      "user_phrase":   "I can't start because it has to be perfect"
    },
    {
      "name":          "The Lonely Struggler",
      "core_dynamic":  "Any barriers + isolation",
      "primary_tool":  "accountability_trinity",
      "user_phrase":   "I am dealing with this alone"
    },
    {
      "name":          "The Ashamed Avoider",
      "core_dynamic":  "Guilt + self-doubt + drift",
      "primary_tool":  "two_envelope_method",
      "user_phrase":   "I feel guilty about everything I have not done"
    },
    {
      "name":          "The Reactive Drifter",
      "core_dynamic":  "Unconscious avoidance + interruptions + wrong timing",
      "primary_tool":  "hourly_anchor",
      "user_phrase":   "Where did the day go?"
    },
    {
      "name":          "The Seasonally Lost",
      "core_dynamic":  "Wrong timing amplifies any other barrier",
      "primary_tool":  "seasonal_map",
      "user_phrase":   "I should be further along by now"
    },
    {
      "name":          "The Impoverished",
      "core_dynamic":  "Scarcity lens + any barrier",
      "primary_tool":  "two_column_inventory",
      "user_phrase":   "I don't have what I need"
    },
    {
      "name":          "The Invaded",
      "core_dynamic":  "External interruptions + any barrier",
      "primary_tool":  "invasion_forecast",
      "user_phrase":   "Everyone keeps interrupting me"
    },
    {
      "name":          "The Overwhelmed",
      "core_dynamic":  "Capacity gap + any barrier",
      "primary_tool":  "capacity_ladder",
      "user_phrase":   "It is just too much"
    },
    {
      "name":          "The Self-Doubting",
      "core_dynamic":  "Inner narrative + any barrier",
      "primary_tool":  "narrative_reset",
      "user_phrase":   "I am not good enough to do this"
    }
  ]
}
IP notice: The 56-profile names, super-cluster names, internal monologues, and breakthrough insights are proprietary to The Ready Mindset. Your API licence permits you to display profile_name and super_cluster to end users within your product. The full taxonomy — all 56 profiles and their descriptions — is not included in API responses and is not licensed for redistribution. Contact hello@myreadymindset.com for licensing enquiries.
Pricing

API Tiers

Start free. Scale as your platform grows. Enterprise includes a dedicated SLA, co-branding rights, and a data processing agreement for healthcare compliance.

Free
$0
500 assessments / month
+Assessment delivery
+MQ score + barrier profile
+Sandbox environment
+Community support
Starter
$97/mo
5,000 assessments / month
+Everything in Free
+Full barrier data + tools
+Client management endpoints
+Webhooks
+Email support
Starter + Pathway
$197/mo
20,000 assessments / month
+Everything in Starter
+90-Day Pathway API
+Pathway progress tracking
+Practitioner management
+Priority support
Enterprise
Custom
Unlimited assessments
+Everything in Starter+Pathway
+White-label option
+HIPAA-ready data agreement
+SLA + dedicated support
+Co-branding rights
Assessment API

Assessment Endpoints

Create sessions, submit answers, and retrieve full MQ profiles including all eight barrier scores, the primary barrier, and tool recommendations.

POST /assessment/sessions Create a new MQ Assessment session ▾
Request Body
ParameterTypeDescription
client_idrequiredstringYour internal client identifier
languagestringAssessment language. Default: en
metadataobjectOptional key-value pairs stored with the session
Response
JSON
{
  "session_id":   "sess_a1b2c3d4",
  "client_id":    "client_abc123",
  "status":       "pending",
  "questions_url": "https://api.myreadymindset.com/v1/assessment/sessions/sess_a1b2c3d4/questions",
  "expires_at":   "2026-08-01T23:59:59Z",
  "created_at":   "2026-07-01T10:00:00Z"
}
POST /assessment/sessions/{session_id}/submit Submit completed assessment answers ▾
Submit all 40 answers in a single request. Each answer is a number 1–5 corresponding to the Likert scale response.
Request Body
{
  "answers": [
    { "question_id": 1, "value": 4 },
    { "question_id": 2, "value": 2 },
    // ... all 40 answers
    { "question_id": 40, "value": 3 }
  ]
}
GET /assessment/sessions/{session_id}/results Retrieve full MQ profile with all barrier scores and tools ▾
Response — Full MQ Profile
JSON
{
  "session_id":     "sess_a1b2c3d4",
  "client_id":      "client_abc123",
  "mq_score":       87,
  "mq_level":       "Constrained",
  "completed_at":   "2026-07-01T10:22:00Z",
  "primary_barrier": "inner_narrative",
  "profile_name":    "The Perfectionist Paralyzed",
  "super_cluster":   "The Perfectionist Paralyzed",

  "barriers": {
    "inner_narrative":    { "score": 22, "level": "high",   "tool": "narrative_reset" },
    "unfinished_business": { "score": 18, "level": "high",   "tool": "two_envelope_method" },
    "autopilot_trap":     { "score": 14, "level": "medium", "tool": "hourly_anchor" },
    "scarcity_lens":      { "score": 11, "level": "medium", "tool": "two_column_inventory" },
    "invasion_factor":    { "score": 8,  "level": "low",    "tool": "invasion_forecast" },
    "timing_mismatch":    { "score": 6,  "level": "low",    "tool": "seasonal_map" },
    "capacity_gap":       { "score": 5,  "level": "low",    "tool": "capacity_ladder" },
    "isolation_trap":     { "score": 3,  "level": "low",    "tool": "accountability_trinity" }
  },

  "tools": {
    "narrative_reset": {
      "name":        "The Narrative Reset",
      "barrier":     "inner_narrative",
      "steps_count": 4,
      "steps_url":   "https://api.myreadymindset.com/v1/tools/narrative_reset"
    }
    // ... tools for all active barriers
  }
}
Client API

Client Endpoints

Create and manage client profiles, retrieve MQ score history, and track barrier changes across reassessments.

POST /clients Create a new client profile ▾
ParameterTypeDescription
external_idrequiredstringYour internal user ID
emailstringClient email for notifications
first_namestringClient first name
practitioner_idstringAssign to a practitioner on creation
metadataobjectCustom key-value pairs
GET /clients/{client_id} Retrieve a client profile and latest MQ scores ▾
Response
{
  "client_id":       "client_abc123",
  "external_id":     "user_7890",
  "email":           "sarah@example.com",
  "first_name":      "Sarah",
  "practitioner_id": "prac_xyz",
  "latest_mq_score": 87,
  "assessment_count":2,
  "pathway_day":     34,
  "created_at":      "2026-06-01T09:00:00Z"
}
GET /clients List all clients with optional filters ▾
Query ParamTypeDescription
practitioner_idstringFilter by practitioner
mq_levelstringFilter: ready, developing, constrained, blocked, crisis
limitintegerResults per page. Default: 20. Max: 100
cursorstringPagination cursor from previous response
GET /clients/{client_id}/score-history MQ score history across all assessments ▾
Response
{
  "client_id": "client_abc123",
  "assessments": [
    {
      "session_id":  "sess_day1",
      "day":          1,
      "mq_score":    112,
      "completed_at":"2026-06-01T09:00:00Z"
    },
    {
      "session_id":  "sess_day30",
      "day":          30,
      "mq_score":    87,
      "completed_at":"2026-07-01T10:22:00Z"
    }
  ],
  "score_delta": -25,
  "trend":       "improving"
}
Pathway API

90-Day Pathway Endpoints

Access the full 90-Day Pathway structure, update task completion, and track a client's progress through all three phases.

GET /clients/{client_id}/pathway Get full pathway progress and current week tasks ▾
Response
{
  "client_id":     "client_abc123",
  "current_day":   34,
  "current_phase": "deepening",
  "current_week":  5,
  "overall_pct":   28,
  "streak_days":   7,

  "phases": {
    "foundation":  { "complete": true,  "pct": 100 },
    "deepening":   { "complete": false, "pct": 15  },
    "integration": { "complete": false, "pct": 0   }
  },

  "current_week_tasks": [
    { "id": "w5t1", "task": "Deploy Invasion Forecast", "complete": true,  "category": "tool"     },
    { "id": "w5t2", "task": "Track defence effectiveness", "complete": false, "category": "tool"     },
    { "id": "w5t3", "task": "Four-barrier analysis",       "complete": false, "category": "reflect"  },
    { "id": "w5t4", "task": "Run all 4 tools in protocol",  "complete": false, "category": "protocol" },
    { "id": "w5t5", "task": "Trinity Challenger daily report","complete": false, "category": "trinity"  }
  ]
}
POST /clients/{client_id}/pathway/progress Mark tasks complete and update pathway progress ▾
Request Body
{
  "task_id":  "w5t2",
  "complete": true,
  "journal_entry": "Optional journal text for this task"
}
Practitioner API

Practitioner Endpoints

List certified practitioners, assign them to clients, and manage practitioner-client relationships within your platform.

GET /practitioners List all certified practitioners in your account ▾
Response
{
  "practitioners": [
    {
      "practitioner_id": "prac_xyz",
      "name":             "Dr. Sarah Okafor",
      "level":            "RMP",
      "client_count":     12,
      "status":           "active"
    }
  ],
  "total": 1
}
POST /clients/{client_id}/practitioner Assign or reassign a practitioner to a client ▾
ParameterTypeDescription
practitioner_idrequiredstringID of the practitioner to assign
Organisation API

Organisation Endpoints

Retrieve team-level MQ data, barrier heatmaps, and bulk invite employees. Designed for HR platforms and enterprise integrations.

GET /organisation/team-mq Team MQ scores, barrier heatmap, and distribution ▾
Response
{
  "org_id":           "org_acme",
  "team_size":        47,
  "assessed":         43,
  "avg_mq_score":     94,
  "mq_distribution": {
    "ready":       6,
    "developing": 14,
    "constrained":18,
    "blocked":     5,
    "crisis":      0
  },
  "barrier_heatmap": {
    "inner_narrative":    16.2,
    "unfinished_business":14.8,
    "autopilot_trap":     12.4,
    "scarcity_lens":      11.9,
    "invasion_factor":    10.2,
    "timing_mismatch":    9.7,
    "capacity_gap":       8.3,
    "isolation_trap":     7.1
  }
}
POST /organisation/invite Bulk invite employees to complete the MQ Assessment ▾
Request Body
{
  "employees": [
    { "email": "alice@acme.com", "department": "Engineering" },
    { "email": "bob@acme.com",   "department": "Sales"       }
  ],
  "message": "Optional custom message in the invite email"
}
Interactive

Live API Tester

Try the API in the sandbox environment. Use your test key (rm_test_demo) to explore responses without affecting live data.

API Request Builder
SANDBOX LIVE
Response
// Click "Run Request" to see a sample response