GritScore Models API

The GritScore Models API provides programmatic access to mental readiness scoring, resilience profiling, and performance insights. Integrate real-time mental performance analytics into your applications.

Base URL: https://api.ironmind.ai/v1

⚠️ Non-Diagnostic Tool: GritScore is a decision support tool, not a clinical diagnostic instrument. It should not be used as the sole basis for clinical decisions.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

To obtain API credentials, contact [email protected]

Rate Limits

API requests are rate-limited to ensure service stability and fair usage.

Limit Type	Value
Requests per minute	60
Concurrent requests	10

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

API Endpoints

GET

List Models

Retrieve a list of all available GritScore models.

GET /v1/models

Response

{
  "models": [
    {
      "id": "gritscore-v2",
      "name": "GritScore v2",
      "description": "Mental readiness scoring model",
      "version": "2.1.0",
      "status": "active"
    }
  ]
}

GET

Get Model Details

Retrieve detailed information about a specific model.

GET /v1/models/{model_id}

Path Parameters

Parameter	Type	Description
model_id	string	Unique model identifier

Response

{
  "id": "gritscore-v2",
  "name": "GritScore v2",
  "description": "Mental readiness scoring model",
  "version": "2.1.0",
  "status": "active",
  "input_signals": ["biometric", "behavioral", "contextual"],
  "output_format": "gritscore_profile"
}

GET

List Model Versions

Retrieve all versions of a specific model.

GET /v1/models/{model_id}/versions

Response

{
  "versions": [
    {
      "version": "2.1.0",
      "released": "2024-01-15",
      "status": "active",
      "changelog": "Improved behavioral signal processing"
    },
    {
      "version": "2.0.0",
      "released": "2023-11-01",
      "status": "deprecated"
    }
  ]
}

POST

Generate GritScore

Generate a GritScore based on input signals from multiple domains.

POST /v1/models/{model_id}:score

Request Body (Minimal)

{
  "signals": {
    "biometric": {
      "heart_rate_variability": 65,
      "resting_heart_rate": 58,
      "sleep_duration": 7.5,
      "sleep_quality": 0.82
    },
    "behavioral": {
      "mrc7_competence": 4.2,
      "mrc7_confidence": 4.5,
      "mrc7_connection": 3.8,
      "mrc7_character": 4.1,
      "mrc7_contribution": 3.9,
      "mrc7_coping": 4.0,
      "mrc7_control": 4.3
    }
  }
}

Request Body (Full)

{
  "signals": {
    "biometric": {
      "heart_rate_variability": 65,
      "resting_heart_rate": 58,
      "sleep_duration": 7.5,
      "sleep_quality": 0.82,
      "activity_level": 8500,
      "recovery_score": 78
    },
    "behavioral": {
      "mrc7_competence": 4.2,
      "mrc7_confidence": 4.5,
      "mrc7_connection": 3.8,
      "mrc7_character": 4.1,
      "mrc7_contribution": 3.9,
      "mrc7_coping": 4.0,
      "mrc7_control": 4.3
    },
    "contextual": {
      "stress_events": 2,
      "workload_intensity": "moderate",
      "social_support": "high"
    },
    "specialized": {
      "sport_specific_load": 450,
      "competition_proximity_days": 7
    }
  },
  "user_id": "user_12345",
  "timestamp": "2024-01-20T10:30:00Z"
}

Response

{
  "gritscore": 72,
  "state": "ready",
  "confidence": 0.89,
  "timestamp": "2024-01-20T10:30:05Z",
  "sub_scores": {
    "physical_readiness": 75,
    "mental_resilience": 68,
    "recovery_status": 71
  },
  "drivers": {
    "positive": ["high_sleep_quality", "strong_hrv"],
    "negative": ["elevated_stress_events"]
  },
  "resilience_profile": {
    "competence": 4.2,
    "confidence": 4.5,
    "connection": 3.8,
    "character": 4.1,
    "contribution": 3.9,
    "coping": 4.0,
    "control": 4.3
  }
}

POST

Explain Score

Get detailed explanations for score drivers and contributing factors.

POST /v1/models/{model_id}:explain

Request Body

{
  "gritscore": 72,
  "signals": { /* same as score endpoint */ }
}

Response

{
  "explanations": [
    {
      "factor": "high_sleep_quality",
      "impact": "+8",
      "description": "Sleep quality above 80% threshold"
    },
    {
      "factor": "elevated_stress_events",
      "impact": "-5",
      "description": "Recent stress events detected"
    }
  ],
  "recommendations": [
    "Maintain current sleep routine",
    "Consider stress management techniques"
  ]
}

Signal Domains

GritScore models accept input signals from five domains. Biometric and Behavioral are required; others are optional but improve accuracy.

1. Biometric (Required)

Physiological data from wearables, apps, and sensors.

Heart Rate Variability (HRV)
Resting Heart Rate
Sleep Duration & Quality
Activity Level
Recovery Score

2. Behavioral (Required)

Self-reported data from the MRC-7 resilience assessment.

Competence (skill mastery)
Confidence (self-belief)
Connection (social bonds)
Character (values alignment)
Contribution (purpose)
Coping (stress management)
Control (agency)

3. Contextual (Optional)

Environmental and situational factors.

Recent stress events
Workload intensity
Social support level

4. Specialized (Optional)

Domain-specific metrics (e.g., sports, military, esports).

Sport-specific training load
Competition proximity
Performance benchmarks

5. Clinical & Expert (Optional)

Professional assessments and clinical data.

Clinician observations
Psychological assessments
Medical history flags

⚠️ PHI Warning: Clinical signals may contain Protected Health Information. Ensure HIPAA compliance when transmitting.

Response Structure

All successful scoring requests return a standardized GritScore profile.

Field	Type	Description
gritscore	integer	Overall score (0-100)
state	string	Classification: ready, caution, at-risk
confidence	float	Model confidence (0-1)
sub_scores	object	Component scores (physical, mental, recovery)
drivers	object	Positive and negative contributing factors
resilience_profile	object	7C resilience dimensions

Error Codes

The API uses standard HTTP status codes and returns detailed error messages.

Code	Status	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for resource
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error occurred

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: biometric.heart_rate_variability",
    "details": {
      "field": "signals.biometric.heart_rate_variability",
      "expected": "number"
    }
  }
}

Need help? Contact API Support

Back to Home API Status