API Reference

Integrate the CHAI Registry into your clinical workflow. This documentation covers how to programmatically submit and update AI model cards via the public API.

What the public API covers today

You can create and update model cards with POST /api/v1/model-cards. There is not yet a documented public endpoint to list or retrieve model cards programmatically—use the CHAI Registry dashboard or contact admin@chai.org if you need bulk access.

Access Restricted

Credentials are required for all endpoints. Contact admin@chai.org to register your organization.

Authentication

The CHAI API uses custom header-based authentication. For POST /api/v1/model-cards, you must include CHAI-REGISTRY-PUBLIC-KEY, CHAI-REGISTRY-SECRET-KEY, and CHAI-REGISTRY-ORG-SLUG.

Base URL

Productionhttps://backend.registry.chai.org

Append the path for your endpoint (e.g. /api/v1/model-cards).

Headers object (TypeScript)

const sampleHeaders: Record<string, string> = {
  "Content-Type": "application/json",
  "CHAI-REGISTRY-PUBLIC-KEY": "<YOUR_PUBLIC_KEY>",
  "CHAI-REGISTRY-SECRET-KEY": "<YOUR_SECRET_KEY>",
  "CHAI-REGISTRY-ORG-SLUG": "<YOUR_ORG_SLUG>",
};

Send the HTTP header CHAI-REGISTRY-ORG-SLUG on POST /api/v1/model-cards. In our API, incoming headers are normalized to request.META keys: hyphens become underscores and the prefix HTTP_ is added, so CHAI-REGISTRY-ORG-SLUG appears as HTTP_CHAI_REGISTRY_ORG_SLUG.

Always set the header value to the organization slug for your Model Cards API keys—the same value shown under Dashboard → API keys & setup.

Situation	Result
Value matches credential org slug (case-insensitive)	Valid for this check; publish can proceed if the rest of the request is valid.
Value does not match credential org	403 — `CHAI-REGISTRY-ORG-SLUG` must match the organization for your API credentials.

Publishing Model Cards

Post/api/v1/model-cards

The payload requires three main objects: user, organization, and model_card. Below are two working examples and the expected server responses.

Case 1: Minimum required fields

All required fields with minimal/short values. Use for testing or when you need only the bare minimum.

Minimum required payload

{
  "user": { "email": "doctor@hospital.org" },
  "organization": { "slug": "acme-health-ai", "name": "Acme Health AI" },
  "model_card": {
    "slug": "heart-disease-predictor-v1",
    "model_developer": "Acme Health AI",
    "developer_contact": "doctor@hospital.org",
    "release_stage": "beta",
    "release_date": "2026-03-15",
    "release_version": "1.0.0",
    "global_availability": "yes",
    "summary": "Risk prediction model for cardiovascular disease.",
    "intended_use_and_workflow": "Clinical decision support.",
    "primary_intended_users": "Clinicians",
    "how_to_use": "Upload patient data via API.",
    "targeted_patient_population": "Adults 18+ with cardiovascular risk factors",
    "cautioned_out_of_scope_settings": "Not for pediatric use.",
    "known_risks_and_limitations": "May underperform on rare conditions.",
    "known_biases_or_ethical_considerations": "Bias monitoring in place.",
    "clinical_risk_level": "medium",
    "outcomes_and_outputs": "Risk score (0–100)",
    "model_type": "classification",
    "input_data_source": "EHR data",
    "output_and_input_data_types": "Structured clinical data",
    "development_data_characterization": "Retrospective dataset",
    "bias_mitigation_approaches": "Reweighting",
    "ongoing_maintenance": "Quarterly updates",
    "funding_source": "Internal R&D",
    "stakeholders_consulted": "Clinicians",
    "peer_reviewed_publications": "",
    "patient_consent_or_disclosure": "Obtained"
  }
}

201

Expected success response

{
  "id": "uuid",
  "slug": "heart-disease-predictor-v1",
  "status": "published",
  "source": "CHAI Public API",
  "notification_type": "Model Card Created",
  "status_message": "Model Card Created successfully. The model card has been saved to the CHAI Registry."
}

Case 2: Full required fields

Same structure with full, realistic content. Recommended for production submissions.

Full required payload

{
  "user": {
    "full_name": "Dr. Sarah Chen",
    "email": "sarah.chen@acme-health.com",
    "role": "ML Engineer"
  },
  "organization": {
    "name": "Acme Health AI",
    "slug": "acme-health-ai"
  },
  "model_card": {
    "slug": "radiology-reader-v2",
    "model_name": "Radiology AI Reader",
    "model_developer": "Acme Health AI",
    "developer_contact": "sarah.chen@acme-health.com",
    "release_stage": "production",
    "release_date": "2026-03-18",
    "release_version": "2.0.0",
    "global_availability": "yes",
    "summary": "A deep learning model for detecting abnormalities in chest X-rays. Trained on retrospective data from 50,000 studies with board-certified radiologist labels.",
    "intended_use_and_workflow": "Integrates with PACS. Radiologist reviews model output before final report.",
    "primary_intended_users": "Radiologists, Emergency physicians",
    "how_to_use": "Upload DICOM via PACS integration or API. Model returns structured findings with confidence scores.",
    "targeted_patient_population": "Adults 18+ presenting for chest imaging",
    "cautioned_out_of_scope_settings": "Not for pediatric chest X-rays. Do not use for portable or low-quality images.",
    "known_risks_and_limitations": "Performance may decrease on non-standard acquisition protocols.",
    "known_biases_or_ethical_considerations": "Trained on US-based populations; external validation recommended.",
    "clinical_risk_level": "medium",
    "outcomes_and_outputs": "Structured findings, confidence scores, differential diagnoses",
    "model_type": "classification",
    "input_data_source": "Chest X-ray DICOM images",
    "output_and_input_data_types": "Image in, structured JSON out",
    "development_data_characterization": "Retrospective, de-identified chest X-rays",
    "bias_mitigation_approaches": "Stratified evaluation, ongoing monitoring",
    "ongoing_maintenance": "Quarterly model updates with new data",
    "funding_source": "Internal R&D and grant funding",
    "stakeholders_consulted": "Radiologists, legal, compliance",
    "peer_reviewed_publications": "Pending publication",
    "patient_consent_or_disclosure": "Institutional IRB approval obtained"
  }
}

201

Expected success response

Same 201 response as Case 1. If the same organization + slug exists, the API updates the record and returns 201 (no 409).

Required Fields

The payload has three top-level objects. Below are all required fields for each. Optional fields may be omitted.

`user` object

Field	Type	Required	Description
email	string	Yes	Valid email (e.g. sarah@company.com)
full_name	string	No	Display name
role	string	No	Role (e.g. "ML Engineer")

`organization` object

Field	Type	Required	Description
slug	string	Yes	URL-safe identifier (lowercase, hyphens)
name	string	Yes	Display name

`model_card` object

All fields below are required for published status. Use slug or solution as the key (both accepted).

Field	Type	Description
slug	string	URL-safe identifier (lowercase, numbers, hyphens)
model_developer	string	Organization or entity developing the model
developer_contact	string	Contact email for the developer
release_stage	string	e.g. prototype, beta, production
release_date	string	Date of release (YYYY-MM-DD)
release_version	string	Version string (e.g. 1.0.0)
global_availability	string	e.g. yes, no, region-specific
summary	string	Brief overview of the model
intended_use_and_workflow	string	How and where the model is used
primary_intended_users	string	Target users (e.g. clinicians)
how_to_use	string	Instructions for using the model
targeted_patient_population	string	Patient population description
cautioned_out_of_scope_settings	string	Settings or uses to avoid
known_risks_and_limitations	string	Documented risks and limits
known_biases_or_ethical_considerations	string	Bias and ethics notes
clinical_risk_level	string	e.g. low, medium, high
outcomes_and_outputs	string	What the model produces
model_type	string	e.g. classification, regression
input_data_source	string	Data sources used
output_and_input_data_types	string	Data type descriptions
development_data_characterization	string	Training/development data
bias_mitigation_approaches	string	Steps to reduce bias
ongoing_maintenance	string	Maintenance and update plan
funding_source	string	Source of funding
stakeholders_consulted	string	Stakeholders involved
peer_reviewed_publications	string	Related publications
patient_consent_or_disclosure	string	Consent or disclosure info

Optional fields (shape)

Most optional fields are plain strings (long-form text is fine). Arrays must be JSON arrays, not comma-separated strings.

Field	Type	Notes
model_name	string	Display name.
regulatory_approval	string	Free text (e.g. clearance status). Often empty until known.
keywords	string[]	Tags such as ["cardiology", "risk"].
foundation_models	string	Base models or dependencies, if any.
security	string	Security posture / controls narrative.
transparency	string	Transparency / documentation narrative.
third_party_information	string	Third-party components or data.
evaluation_references	string	Evaluations, benchmarks, or links as text.
clinical_trial	string	Trial identifiers or narrative.
reimbursement_status	string	Billing / coverage notes.
bibliography	string	References or citations as text.
ehr_compatibility	string[]	EHR vendors, e.g. ["Epic", "Cerner"].
regulatory_compliance	string	Compliance framing or standards referenced.
key_metrics	object	Structured metrics object—see below.

For key_metrics, use the exact object shape in Key Metrics (optional)—including nested usefulness, fairness, and safety and the metric value kind variants shown there. It must be a JSON object in the payload, not a string.

Slug rules

Lowercase letters, numbers, and hyphens only
No spaces or uppercase
Example: heart-disease-predictor-v1

Key Metrics (optional)

If you include key_metrics, it must be an object with optional usefulness, fairness, and safety sections:

key_metrics structure

{
  "key_metrics": {
    "usefulness": {
      "metric_goal": "AUC-ROC ≥ 0.85",
      "results": [
        { "label": "AUC-ROC", "value": { "kind": "single", "value": 0.89 } }
      ],
      "interpretation": "Meets target.",
      "test_type": "Retrospective",
      "testing_data_description": "Holdout set",
      "validation_process_and_justification": "5-fold CV"
    },
    "fairness": { "metric_goal": "", "results": [], "interpretation": "", "test_type": "", "testing_data_description": "", "validation_process_and_justification": "" },
    "safety": { "metric_goal": "", "results": [], "interpretation": "", "test_type": "", "testing_data_description": "", "validation_process_and_justification": "" }
  }
}

Metric value kinds: single, estimate_ci, mean_sd, median_iqr

Response Handling

We use standard HTTP status codes to indicate the success or failure of an API request.

201Created

Model card successfully saved/updated.

400Bad Request

Missing/invalid payload, invalid email, invalid slug format.

401Unauthorized

Missing CHAI-REGISTRY-PUBLIC-KEY or CHAI-REGISTRY-SECRET-KEY headers or invalid values.

403Forbidden

Wrong CHAI-REGISTRY-ORG-SLUG (must match the org for your keys), invalid keys, org/domain rules, or organization not authorized to create subsidiaries. Always send the org slug header; omitting it is not a supported client contract.

409Conflict

Rare slug conflict.

500Internal Server Error

Server or upstream (e.g. Supabase) failure.

503Service Unavailable

Supabase not configured or unreachable.

Error response shape

Error responses include detail and status_message:

{
  "detail": "Valid user email is required.",
  "status_message": "400 Bad Request — The request body was invalid or missing required fields."
}

Dashboard Access

Any user who created model cards through the API can still access the CHAI Registry dashboard to continue editing. The first successful API submission for an email often provisions a user record without a password you chose, so when you sign in to the dashboard you may need to use Forgot password once to set a password for that account.

Note: Use the same email address as in your API submissions. If sign-in fails or you have never set a password, complete the password reset flow to establish one.