EffortGuard API v1

REST endpoints powering external integrations including the EffortGuard MCP connector for Claude.

Authentication

Every request must include an API key as a Bearer token. Generate keys in Settings → API Keys (owner or admin role required).

Authorization: Bearer eg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL: https://effortguard.com/api/v1

Error format

All errors return JSON with this shape. Common codes: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), RATE_LIMITED (429), INVALID_BODY (400), INTERNAL_ERROR (500).

{
  "error": "Invalid or expired API key",
  "code": "UNAUTHORIZED"
}

Rate limits

Each API key is limited to 100 requests/minute and 10,000 requests/day. Exceeding either returns a 429 with retry_after_seconds.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retry_after_seconds": 60
}

MCP Server — Claude.ai Integration

EffortGuard exposes a remote MCP (Model Context Protocol) server so you can use Claude.ai or Claude Desktop to query live compliance data in natural language. No local installation required.

Remote MCP URL

https://effortguard.com/mcp

Connect in Claude.ai (web)

Go to claude.ai in your browser
Click your profile icon
Go to Settings
Click Connectors or Integrations
Click Add custom connector
Enter URL: https://effortguard.com/mcp
When prompted for authentication, enter your API key from Settings → API Keys
Click Connect

Connect in Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "effortguard": {
      "type": "http",
      "url": "https://effortguard.com/mcp",
      "headers": {
        "Authorization": "Bearer eg_live_your_key_here"
      }
    }
  }
}

Available MCP tools

get_compliance_health — institution-wide score
get_effort_gaps — committed vs actual effort
get_prior_approval_required — 2 CFR §200.308 triggers
get_compliance_flags — open flags with citations
get_award_detail — full detail for one award
get_bridge_cost_exposure — uncovered salary exposure
update_prior_approval_status — write (requires write scope)
check_nih_threshold — NIH 76% rule (NIH GPS §9.2)
get_retention_status — 2 CFR §200.333 retention window
generate_compliance_brief — formatted leadership brief

Protocol: JSON-RPC 2.0 over HTTP, MCP version 2025-03-26. Same Bearer-token auth and rate limits as the REST API.

GET/effort-gapsrequires read scope

List PIs with effort gaps between committed and actual.

Query parameters

min_gap_pct — Minimum gap percent to return (default 0)
severity — critical | high | medium
limit — Default 50, max 200

Example response

{
  "data": [
    {
      "pi_id": "uuid",
      "pi_name": "Dr. Jane Smith",
      "award_id": "R01-AB123456",
      "sponsor": "NIH/NIAID",
      "sponsor_type": "nih",
      "committed_effort_pct": 25,
      "actual_effort_pct": 18,
      "gap_pct": 7,
      "gap_direction": "under",
      "bridge_cost_exposure": 12450,
      "requires_prior_approval": true,
      "highest_flag_severity": "high",
      "open_flag_count": 2
    }
  ],
  "total": 1,
  "generated_at": "2026-05-26T19:00:00Z"
}

GET/prior-approvalrequires read scope

Awards requiring 2 CFR §200.308 prior approval.

Query parameters

status — Filter by prior_approval_status
limit — Default 50

Example response

{
  "data": [
    {
      "award_id": "R01-AB123456",
      "pi_name": "Dr. Jane Smith",
      "sponsor": "NIH",
      "committed_effort_pct": 25,
      "actual_effort_pct": 18,
      "gap_pct": 7,
      "prior_approval_status": "required_pending",
      "regulation_cite": "2 CFR §200.308",
      "flag_created_at": "2026-04-12T09:30:00Z"
    }
  ],
  "total": 1
}

GET/compliance-flagsrequires read scope

Open compliance flags across the institution.

Query parameters

severity — critical | high | amber | red
flag_type — e.g. effort_gap, prior_approval_required
pi_id — Filter to a single PI
limit — Default 100, max 500

Example response

{
  "data": [
    {
      "flag_id": "uuid",
      "award_id": "R01-AB123456",
      "pi_name": "Dr. Jane Smith",
      "flag_type": "effort_gap",
      "severity": "high",
      "regulation_cite": "NIH GPS §9.2",
      "message": "effort_gap: nih_key_personnel_threshold",
      "status": "open",
      "created_at": "2026-04-12T09:30:00Z"
    }
  ],
  "total": 1
}

GET/awards/{award_id}requires read scope

Full compliance detail for one award (open flags, corrective actions, effort history).

Example response

{
  "data": {
    "award_id": "R01-AB123456",
    "pi_name": "Dr. Jane Smith",
    "sponsor": "NIH",
    "sponsor_type": "nih",
    "committed_effort_pct": 25,
    "actual_effort_pct": 18,
    "gap_pct": 7,
    "gap_direction": "under",
    "prior_approval_status": "required_pending",
    "bridge_cost_exposure": 12450,
    "open_flags": [],
    "corrective_actions": [],
    "effort_history": []
  }
}

GET/compliance-healthrequires read scope

Institution-wide compliance health score and summary.

Example response

{
  "data": {
    "health_score": 87,
    "total_awards": 42,
    "awards_with_gaps": 6,
    "prior_approval_required": 3,
    "critical_flags": 0,
    "high_flags": 2,
    "total_bridge_cost_exposure": 48230.45,
    "generated_at": "2026-05-26T19:00:00Z"
  }
}

GET/bridge-costrequires read scope

Bridge cost exposure totals and per-PI breakdown.

Example response

{
  "data": {
    "total_exposure": 48230.45,
    "by_pi": [
      {
        "pi_name": "Dr. Jane Smith",
        "award_count": 2,
        "total_exposure": 18900,
        "awards": [
          {
            "award_id": "R01-AB123456",
            "exposure": 12450,
            "gap_pct": 7
          }
        ]
      }
    ]
  }
}

PATCH/awards/{award_id}/prior-approval-statusrequires write scope

Update prior approval status on an award. Requires write scope.

Example response

{
  "data": {
    "id": "uuid",
    "account_number": "R01-AB123456",
    "prior_approval_status": "required_approved",
    "prior_approval_approved_at": "2026-05-26"
  }
}

GET/retention-statusrequires read scope

Records nearing the 2 CFR §200.334 three-year retention expiry.

Example response

{
  "data": {
    "expiring_within_30_days": [],
    "expiring_within_90_days": [
      {
        "award_id": "R01-AB123456",
        "pi_name": "Dr. Jane Smith",
        "sponsor": "NIH",
        "final_expenditure_report_date": "2023-06-15",
        "retention_expires_at": "2026-06-15"
      }
    ],
    "total_monitored_records": 14
  }
}

Code examples

curl

curl -H "Authorization: Bearer eg_live_YOUR_KEY" \
  https://effortguard.com/api/v1/compliance-health

JavaScript

const res = await fetch("https://effortguard.com/api/v1/compliance-health", {
  headers: { Authorization: "Bearer " + process.env.EFFORTGUARD_API_KEY },
});
const { data } = await res.json();
console.log(data.health_score);