Mango Docs
v1.0 (Latest)
GitHub

Introduction

Welcome to the Mango Trust & Verification API documentation.

Mango provides Trust Infrastructure for Medical AI. We decouple vetting, continuous monitoring, and provenance logging from the annotation interface. Startups and dataset developers can integrate Mango to verify clinician identity, guarantee session safety, and establish legally binding cryptographic audit trails for medical data annotations.

Core Concept: Mango never stores patient PII. It focuses entirely on validating the clinician's credentials and behavioral security.

Key Capabilities

Clinician Vetting

Real-time checks against state provider registries and exclusion blacklists.

Session Tracking

Continuous biometric checks and IP tracking to prevent session hijacking or helper handoffs.

Mango Trail

RSA-2048 signing of label decisions to provide absolute, tamper-evident regulatory compliance.

Media Management

Unified uploader for storing profiles and webcam snaps safely.

Authentication

Secure your API requests to Mango.

Mango API implements dual-layer security. Public/Integrator routes are authenticated via an API Key in headers, while User-specific routes require standard JWT tokens.

Header Requirements

Header Type Description
X-API-KeyRequired String Your developer API Key, apply for one here.
Authorization String Standard JWT bearer token: Bearer <token>. Required for all annotator/session routes.
Example Request 
curl -H "X-API-Key: mng_dev_your_key" \
     -H "Authorization: Bearer jwt_user_token" \
     https://mango-api-egk2.onrender.com/health

Error Codes

API error response code mapping.

Mango returns consistent, structured error responses. Every error response includes an ErrorCode and a descriptive Message.

Error Code HTTP Status Description
UNAUTHORIZED 401 Unauthorized The provided JWT bearer token or API key is invalid or expired.
MISSING_API_KEY 401 Unauthorized The required X-API-Key header is missing from the request.
BAD_REQUEST 400 Bad Request The request payload is invalid or required fields are missing.
NOT_FOUND 404 Not Found The requested resource (e.g. session, user) does not exist.
EXCLUDED_PROVIDER 400 Bad Request The clinician failed regulatory status checks.
INVALID_NPI 400 Bad Request The NPI provided could not be verified.
CONTACT_EMAIL_NOT_SET 400 Bad Request No developer configuration exists to route approvals.
INTERNAL_SERVER_ERROR 500 Internal Error An unexpected error occurred on the server.

Upload Media

POST /media/upload

Accepts raw image files (multipart/form-data), uploads them directly, and returns a secure HTTPS CDN URL. Use this to upload doctor reference photos and session webcam checks.

Form Parameters

Field Type Description
fileRequired file The portrait image file (JPEG/PNG, max 10MB).

Response Payload

200 Success Response 
{
  "ErrorCode": "",
  "Message": "file uploaded successfully",
  "Data": {
    "url": "https://res.cloudinary.com/qfzib2qb/image/upload/v1785876690/webcams/dr_carter.jpg"
  }
}

Submit Verification

POST /annotator/verify

Submits credentials for background verification, triggering our automated checks to verify the clinician's active license and status.

Request Body

Field Type Description
npiRequired String The clinician's 10-digit National Provider Identifier.
reference_photo_urlRequired String Secure CDN URL representing their official reference portrait.

Response Payload

202 Accepted Response 
{
  "ErrorCode": "",
  "Message": "Verification request submitted successfully",
  "Data": {
    "id": 12,
    "user_id": 4,
    "npi": "1447259338",
    "reference_photo_url": "https://res.cloudinary.com/qfzib2qb/image/upload/v1785876690/webcams/dr_carter.jpg",
    "status": "pending",
    "npi_status": "pending",
    "oig_status": "pending"
  }
}

Check Verification Status

GET /annotator/verification-status

Retrieves the status of the clinician's latest vetting request.

Response Payload (Success)

200 OK Response 
{
  "ErrorCode": "",
  "Message": "Verification status retrieved",
  "Data": {
    "id": 12,
    "user_id": 4,
    "npi": "1447259338",
    "status": "completed",
    "npi_status": "passed",
    "oig_status": "passed"
  }
}

Retrieve Credential Badge

GET /annotator/badge

Obtains an anonymized compliance badge. This badge token represents the doctor's verified state and specialty, allowing them to label data without exposing PII (name/NPI).

Response Payload

200 OK Response 
{
  "ErrorCode": "",
  "Message": "Credential badge retrieved",
  "Data": {
    "id": 8,
    "user_id": 4,
    "badge_token": "BADGE-NY-RADIOLOGY-83FA9",
    "specialty": "Radiology",
    "credential_type": "MD"
  }
}

Start Work Session

POST /annotator/sessions/start

Begins an active, secure workspace session. Binds the clinician's current IP address and hardware configuration to their active badge token.

Request Body

Field Type Description
device_infoRequired String Description of browser/hardware (e.g. Chrome Mac OS X).

Response Payload

201 Created Response 
{
  "ErrorCode": "",
  "Message": "Session started successfully",
  "Data": {
    "id": 145,
    "badge_token": "BADGE-NY-RADIOLOGY-83FA9",
    "start_ip": "172.56.21.90",
    "status": "active"
  }
}

Send Heartbeat Telemetry

POST /annotator/sessions/{id}/heartbeat

Reports user presence. Returns instant 200. If any anomaly is detected, we flag the session in the background.

Violation Rules: A session's status transitions to "flagged" permanently if the incoming IP deviates from the session's start IP, or if a facial mismatch is detected.

Request Body

Field Type Description
webcam_snapshot_url String Secure CDN image URL. If it contains "mismatch", it forces a security violation for test runs.
click_count Int Number of mouse clicks in the interval.
key_press_count Int Number of keypresses in the interval.
mouse_movement_delta Int Aggregate mouse pixels traveled.

Check Session Status

GET /annotator/sessions/{id}/status

Retrieves the status of the clinician's active session, allowing integrators to track background violations.

Response Payload

200 OK Response 
{
  "ErrorCode": "",
  "Message": "session status retrieved",
  "Data": {
    "id": 145,
    "user_id": 4,
    "status": "active",
    "rejection_reason": null
  }
}

End Work Session

POST /annotator/sessions/{id}/end

Gracefully closes the session. If the session was flagged mid-work, the final session state persists as "flagged" to preserve compliance tracking.

Response Payload

200 OK Response 
{
  "ErrorCode": "",
  "Message": "session ended successfully",
  "Data": {
    "id": 145,
    "status": "completed",
    "ended_at": "2026-08-04T15:20:00Z"
  }
}

Sign Label Decision

POST /annotator/trail/sign

Signs a specific annotation action. Generates an RSA-2048 digital signature verifying the integrity and qualifications of the clinician performing the work.

Request Body

Field Type Description
session_idRequired Int ID of the active secure session.
data_point_idRequired String Identifier of the medical asset (e.g. img_99187).
label_valueRequired String The diagnostic classification made (e.g. "malignant_nodule").

Response Payload

201 Created Response 
{
  "ErrorCode": "",
  "Message": "Audit trail record created successfully",
  "Data": {
    "id": "7fa291b8-202b-426b-9c71-081831c2a101",
    "signature": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
  }
}

Verify Ledger Proof

GET /trail/verify/{id}

A public/auditor facing route to verify the authenticity and security status of an annotation decision without exposing clinician PII.

Response Payload

200 OK Response 
{
  "ErrorCode": "",
  "Message": "Audit trail record verified successfully",
  "Data": {
    "is_valid": true,
    "data_point_id": "img_99187",
    "label_value": "malignant_nodule",
    "badge_token": "BADGE-NY-RADIOLOGY-83FA9",
    "specialty": "Radiology",
    "credential_type": "MD",
    "session_status": "completed",
    "session_rejection_reason": null,
    "signed_at": "2026-08-04T15:10:00Z"
  }
}