Mango Foundry
v1.0 (Latest)
GitHub

Introduction

Trust infrastructure for medical AI annotation.

Mango Foundry lets you verify that every clinician labeling your medical data is who they say they are. Submit a name and NPI, get back a real-time check against federal registries and OIG exclusion lists. Every approved annotation decision is then signed with an RSA-2048 cryptographic signature and recorded on the Mango Trail ledger, giving you a tamper-evident, publicly auditable proof of qualified work.

Privacy by design: Mango never stores patient data. Only clinician credential status is retained, and annotation decisions are recorded as signed hashes, not raw content.

Key Capabilities

Trusted Medical Infra

Real-time NPI validation and OIG exclusion checks, ensuring every clinician labeling your data is actively licensed and regulatory-clear.

Mango Trail™

RSA-2048 cryptographic signing of every annotation decision. Tamper-evident, publicly auditable, and regulator-ready.

Authentication

Secure your API requests to Mango.

All requests to the Mango API must be authenticated using your developer API key. Pass it via the X-API-Key header on every request. Note: GET /v1/trail/verify/{id} is a public auditor endpoint with no API key required.

Header Requirements

Header Required Description
X-API-Key Yes Your developer API key. Apply for one here.
Example Request 
curl -X POST \
     -H "X-API-Key: mng_dev_your_key" \
     -H "Content-Type: application/json" \
     -d '{"full_name":"Dr. Nelda LeJeune","npi":"1447259338"}' \
     https://api.mangotrail.ai/v1/annotator/verify

Error Codes

API error response code mapping.

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

Error Reference

Error Code HTTP Status Description
MISSING_API_KEY 401 Unauthorized The required X-API-Key header is missing from the request.
UNAUTHORIZED 401 Unauthorized The provided API key is invalid, inactive, or revoked.
BAD_REQUEST 400 Bad Request The request payload is invalid or required fields are missing.
INVALID_NPI 400 Bad Request The NPI provided is invalid or could not be verified against the NPI registry.
EXCLUDED_PROVIDER 400 Bad Request The clinician failed regulatory status checks or is on an OIG exclusion list.
NOT_FOUND 404 Not Found The requested resource (e.g. trail record or credential badge) does not exist.
INTERNAL_SERVER_ERROR 500 Internal Error An unexpected error occurred on the server.

Submit Verification

POST /v1/annotator/verify

Submits a clinician's credentials for real-time background verification, triggering automated NPI registry and OIG exclusion checks.

Request Body

Field Type Description
full_nameRequired String The clinician's full legal name, as it appears on their license.
npiRequired String The clinician's 10-digit National Provider Identifier.

Response Payload

202 Accepted Response 
{
  "ErrorCode": "",
  "Message": "Verification request submitted successfully",
  "Data": {
    "id": 12,
    "npi": "1447259338",
    "status": "pending",
    "npi_status": "pending",
    "oig_status": "pending"
  }
}

Retrieve Credential Badge

GET /v1/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": {
    "badge_token": "BADGE-NY-RADIOLOGY-83FA9",
    "specialty": "Radiology",
    "credential_type": "MD"
  }
}

Verify Ledger Proof

GET /v1/trail/verify/{id}

A public auditor-facing route. Verifies the authenticity of an annotation decision on the Mango Trail ledger without exposing any clinician PII. No API key required. This endpoint is open to anyone.

Path Parameters

Parameter Type Description
idRequired Integer The unique Mango Trail record ID (e.g. 101) returned when an annotation decision is signed on the ledger.

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"
  }
}

Batch Verify Ledger Proofs

POST /v1/trail/verify/batch

A public auditor-facing endpoint for bulk dataset validation. Verifies up to 1,000 Mango Trail ledger records in a single request. No API key required.

Request Body

Field Type Description
idsRequired Array of Integers Array of Mango Trail record IDs to verify (maximum 1,000 per request).

Response Payload

200 OK Response 
{
  "ErrorCode": "",
  "Message": "batch verification complete",
  "Data": {
    "total_checked": 2,
    "valid_count": 2,
    "invalid_count": 0,
    "results": [
      {
        "id": 101,
        "is_valid": true,
        "data_point_id": "img_99187",
        "action_type": "label",
        "badge_token": "BADGE-NY-RADIOLOGY-83FA9",
        "specialty": "Radiology",
        "credential_type": "MD",
        "signed_timestamp": "2026-08-15T09:40:00Z"
      },
      {
        "id": 102,
        "is_valid": true,
        "data_point_id": "img_99188",
        "action_type": "label",
        "badge_token": "BADGE-NY-RADIOLOGY-83FA9",
        "specialty": "Radiology",
        "credential_type": "MD",
        "signed_timestamp": "2026-08-15T09:41:00Z"
      }
    ]
  }
}