Skip to main content

Update Custom Model

Update a custom model's metadata (name and/or description). Training configuration fields (language, base_model) cannot be changed after creation.

Endpoint​

POST /api/v3/custom_models/{id}

Authentication​

Requires API key with custom_models:write scope.

Request​

Path Parameters​

ParameterTypeRequiredDescription
idintegerYesModel ID

Headers​

HeaderValueRequired
AuthorizationBearer YOUR_API_KEYYes
Content-Typeapplication/jsonYes

Request Body​

{
  "name": "Medical Cardiology EN v2",
  "description": "Updated description with enhanced terminology"
}

Parameters​

ParameterTypeRequiredDescriptionConstraints
namestringNoUpdated model name1-200 characters
descriptionstringNoUpdated description0-1000 characters

Note: At least one field must be provided.

Response​

Success Response​

Status Code: 200 OK

Returns complete updated model object:

{
  "id": 123,
  "model_key": "custom_model_123",
  "name": "Medical Cardiology EN v2",
  "description": "Updated description with enhanced terminology",
  "language": "en",
  "base_model": "medical",
  "training_status": 4,
  "status_message": "Training completed successfully",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-17T14:20:00Z",
  "training_metrics": {
    "word_error_rate": 12.5,
    "accuracy_improvement": 18.7
  }
}

Examples​

cURL​

# Update name only
curl -X POST https://api.scriptix.io/api/v3/custom_models/123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Medical Cardiology EN v2"}'

# Update description only
curl -X POST https://api.scriptix.io/api/v3/custom_models/123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Enhanced cardiology model"}'

# Update both
curl -X POST https://api.scriptix.io/api/v3/custom_models/123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medical Cardiology EN v2",
    "description": "Enhanced with additional training data"
  }'

Python​

import requests

def update_model(model_id, name=None, description=None):
    url = f"https://api.scriptix.io/api/v3/custom_models/{model_id}"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    data = {}
    if name:
        data['name'] = name
    if description is not None:  # Allow empty string
        data['description'] = description

    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Update name
model = update_model(123, name="Medical Cardiology EN v2")

# Update description
model = update_model(123, description="Enhanced model")

# Update both
model = update_model(
    123,
    name="Medical Cardiology EN v2",
    description="Retrained with 50+ hours of data"
)

JavaScript​

const updateModel = async (modelId, updates) => {
  const response = await axios.post(
    `https://api.scriptix.io/api/v3/custom_models/${modelId}`,
    updates,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data;
};

// Usage
const model = await updateModel(123, {
  name: 'Medical Cardiology EN v2',
  description: 'Enhanced with additional data'
});

Error Responses​

400 Bad Request - Validation Error​

{
  "error": "Validation Error",
  "message": "Invalid field values",
  "details": {
    "name": "Name cannot be empty"
  }
}

400 Bad Request - No Fields Provided​

{
  "error": "Bad Request",
  "message": "At least one field (name or description) must be provided"
}

404 Not Found​

{
  "error": "Not Found",
  "message": "Model not found"
}

401 Unauthorized​

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Immutable Fields​

These fields cannot be changed after creation:

  • language - Model language is fixed
  • base_model - Base model type is fixed
  • model_key - Auto-generated identifier
  • id - Unique model ID
  • training_status - Managed by system
  • created_at - Creation timestamp

Why immutable? Changing language or base model would require complete retraining with different architecture, so create a new model instead.

Use Cases​

Version Tracking​

Add version numbers to track model iterations:

# Initial model
create_model(name="Medical Cardiology EN v1")

# After retraining with more data
update_model(123, name="Medical Cardiology EN v2")
update_model(123, description="Retrained Jan 2025 with 30 additional hours")

Documentation Updates​

Track training details in description:

description = """
Medical cardiology model
Training data: 50 hours MRI/CT scan reports
Speakers: 15 physicians
WER: 12.5%
Last updated: Jan 15, 2025
"""

update_model(123, description=description)

Clear Description​

# Remove description
update_model(123, description="")

# Or set to null
update_model(123, description=None)

Best Practices​

Naming Conventions​

Include metadata in model names:

  • Domain: Medical, Legal, Technical
  • Specialty: Cardiology, Contracts, Support
  • Version: v1, v2, 2025
  • Language: EN, NL, DE

Examples:

  • Medical-Cardiology-EN-v2
  • Legal-Contracts-NL-2025
  • Tech-Support-DE-v3

Description Format​

Use descriptions to document:

  • Training data source
  • Audio hours used
  • Number of speakers
  • Performance metrics
  • Last update date
  • Intended use case

Example:

Cardiology model trained on 50 hours of MRI and CT scan
report dictation from 15 physicians. WER: 12.5%, Accuracy
improvement: 18.7%. Updated Jan 2025.

Rate Limits​

  • Requests: 50 requests/hour
  • Concurrent: 5 concurrent requests

See Data Models for complete schema reference.