Custom Models API - Data Models

Complete reference for all request and response schemas used in the Custom Models API. This guide documents data structures, field types, validation rules, and example payloads.

Model Object Schema

The core custom model object returned by most endpoints.

Complete Model Object

{
  "id": 123,
  "model_key": "custom_model_123",
  "name": "Medical Cardiology EN v2",
  "description": "Cardiology model trained on 50+ hours of MRI and CT report dictation",
  "language": "en",
  "base_model": "medical",
  "training_status": 4,
  "status_message": "Training completed successfully",
  "training_progress": 100,
  "error": null,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-16T15:30:00Z",
  "started_training_at": "2025-01-16T08:00:00Z",
  "finished_training_at": "2025-01-16T15:30:00Z",
  "failed_at": null,
  "training_metrics": {
    "word_error_rate": 12.5,
    "character_error_rate": 8.3,
    "accuracy_improvement": 18.7,
    "training_hours": 7.5,
    "test_word_error_rate": 11.2
  }
}

Field Specifications

Field	Type	Required	Description	Constraints
id	Integer	Yes	Unique model identifier	Auto-generated, immutable
model_key	String	Yes	Internal model key reference	Auto-generated, format: custom_model_{id}
name	String	Yes	Human-readable model name	1-200 characters
description	String	No	Model description and notes	0-1000 characters, nullable
language	String	Yes	Base language code	ISO 639-1 (2 letters), immutable
base_model	String	Yes	Base model type	Enum: general, medical, legal, technical, immutable
training_status	Integer	Yes	Training status code	Enum: 1-5 (see Training Status section)
status_message	String	Yes	Human-readable status	Auto-generated based on training_status
training_progress	Integer	Conditional	Training progress percentage	0-100, only present when status=3
error	String	Conditional	Error message	Only present when status=5
created_at	String	Yes	Creation timestamp	ISO 8601 format, immutable
updated_at	String	Yes	Last update timestamp	ISO 8601 format, auto-updated
started_training_at	String	Conditional	Training start timestamp	ISO 8601, present when training started
finished_training_at	String	Conditional	Training completion timestamp	ISO 8601, present when status=4
failed_at	String	Conditional	Training failure timestamp	ISO 8601, present when status=5
training_metrics	Object	Conditional	Training performance metrics	Present when status=4 (see Training Metrics)

Training Status Codes

Status Enumeration

Code	Name	Description	Transitions
1	Not Running	Model created, no data uploaded	→ 2 (data upload)
2	Ready to Run	Data uploaded, ready to train	→ 3 (start training)
3	Running	Training in progress	→ 4 (success) or → 5 (failure)
4	Success	Training completed successfully	Terminal state
5	Failed	Training failed with error	Terminal state

Related Documentation

• Create - Create model endpoint details
• List - List models with pagination
• Get - Retrieve model details
• Update - Update model metadata
• Delete - Delete model
• TrainingData - Upload training data
• Train - Start training and monitor progress
• Custom Models Overview - Complete guide

---

Reference for success! Use this data models guide to understand request/response structures and build robust custom model integrations.