Model Registry API

The Model Registry API provides CRUD operations and auto-discovery for the LLM model inventory. The registry supports OCC SR 11-7 model risk management by maintaining a formal catalog of all models in use, their risk tiers, and validation status.

All endpoints require admin authentication (Authorization: Bearer <admin-token>) and are served from the platform base URL.

---

Endpoints

Method	Path	Description
GET	/api/v1/admin/models	List registered models
POST	/api/v1/admin/models	Register a new model
POST	/api/v1/admin/models/discover	Auto-discover unregistered models from audit log
GET	/api/v1/admin/models/{id}	Get a single model entry
PUT	/api/v1/admin/models/{id}	Update a model entry
DELETE	/api/v1/admin/models/{id}	Delete a model entry
GET	/api/v1/admin/model-inventory-export	Export full inventory as CSV or JSON

---

GET /api/v1/admin/models

List all registered models with optional filtering and pagination.

Query Parameters

Parameter	Type	Description
risk_tier	string	Filter by risk tier: tier_1, tier_2, tier_3, tier_4, unclassified
validation_status	string	Filter by status: draft, pending_validation, in_validation, needs_remediation, validated, deprecated, unclassified
provider	string	Filter by provider name (e.g., openai, anthropic, cohere)
search	string	Full-text search across model_id, display_name, and description
limit	integer	Page size (default: 50, max: 500)
offset	integer	Pagination offset (default: 0)

Response

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "model_id": "gpt-4o",
      "provider": "openai",
      "display_name": "GPT-4o",
      "risk_tier": "tier_2",
      "validation_status": "validated",
      "owner": "ml-platform-team",
      "description": "OpenAI GPT-4o — primary production model",
      "tags": ["production", "general-purpose"],
      "request_count_30d": 142857,
      "first_seen_at": "2026-01-15T09:30:00Z",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-03-01T14:22:00Z"
    }
  ],
  "total": 23,
  "limit": 50,
  "offset": 0
}

Example

# List all tier_1 models
curl "https://your-platform/api/v1/admin/models?risk_tier=tier_1" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Search for Claude models, paginated
curl "https://your-platform/api/v1/admin/models?search=claude&limit=10&offset=0" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

---

POST /api/v1/admin/models

Register a new model in the inventory.

Request Body

{
  "model_id": "claude-opus-4-6",
  "provider": "anthropic",
  "display_name": "Claude Opus 4.6",
  "risk_tier": "tier_2",
  "validation_status": "draft",
  "owner": "ml-platform-team",
  "description": "Anthropic Claude Opus 4.6 — high-capability reasoning model",
  "tags": ["production", "reasoning"]
}

Field	Type	Required	Description
model_id	string	Yes	Canonical model identifier (e.g., gpt-4o, claude-opus-4-6)
provider	string	Yes	Model provider (e.g., openai, anthropic, cohere, google)
display_name	string	No	Human-readable name
risk_tier	string	No	OCC SR 11-7 tier: tier_1–tier_4 or unclassified (default)
validation_status	string	No	Lifecycle status (default: draft)
owner	string	No	Team or individual responsible for model governance
description	string	No	Free-text description
tags	array[string]	No	Searchable tags

Response

201 Created — returns the created model entry:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "model_id": "claude-opus-4-6",
  "provider": "anthropic",
  "display_name": "Claude Opus 4.6",
  "risk_tier": "unclassified",
  "validation_status": "draft",
  "owner": "ml-platform-team",
  "description": "Anthropic Claude Opus 4.6 — high-capability reasoning model",
  "tags": ["production", "reasoning"],
  "created_at": "2026-03-13T10:00:00Z",
  "updated_at": "2026-03-13T10:00:00Z"
}

Error Codes

Code	Error	Description
409 Conflict	model_already_exists	A model with the same (model_id, provider) combination already exists
422 Unprocessable	validation_error	Invalid field values (e.g., unknown risk_tier value)

---

POST /api/v1/admin/models/discover

Scan the audit log for model IDs that have been used but are not yet registered in the inventory. Creates draft entries for all discovered unregistered models.

This endpoint supports OCC SR 11-7 Section III.B requirement to maintain a comprehensive model inventory.

Request Body

{
  "lookback_days": 30,
  "auto_assign_tier": false,
  "dry_run": false
}

Field	Type	Required	Description
lookback_days	integer	No	How many days of audit log to scan (default: 30, max: 365)
auto_assign_tier	boolean	No	Automatically assign risk tiers based on provider inference (default: false)
dry_run	boolean	No	If true, returns what would be created without persisting (default: false)

Response

{
  "discovered": 5,
  "created": 3,
  "existing": 2,
  "models": [
    {
      "model_id": "gpt-4o-mini",
      "provider": "openai",
      "status": "created",
      "risk_tier": "unclassified",
      "validation_status": "unclassified",
      "request_count_30d": 8432,
      "first_seen_at": "2026-02-28T14:00:00Z"
    },
    {
      "model_id": "claude-haiku-4-5",
      "provider": "anthropic",
      "status": "existing",
      "risk_tier": "tier_3",
      "validation_status": "validated",
      "request_count_30d": 21150,
      "first_seen_at": "2026-01-10T09:00:00Z"
    }
  ]
}

Field	Description
discovered	Total number of distinct model IDs found in the audit log
created	Number of new registry entries created
existing	Number of model IDs already in the registry
models[].status	created (new entry) or existing (already registered)
models[].request_count_30d	Request count in the last 30 days from the audit log
models[].first_seen_at	Earliest audit log entry for this model ID

Provider Inference

When auto_assign_tier=true, the discovery endpoint infers risk tiers from the model ID format:

Pattern	Inferred provider	Default tier
gpt-*	openai	tier_2
claude-*	anthropic	tier_2
gemini-*	google	tier_2
command-*	cohere	tier_3
Unrecognized	unknown	unclassified

Automatically assigned tiers are starting points only. Review and update them through your formal model validation process before considering inventory complete for SR 11-7 compliance.

Dry Run

Use dry_run: true to preview discovery results without modifying the registry:

curl -X POST https://your-platform/api/v1/admin/models/discover \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lookback_days": 90, "dry_run": true}'

Dry run response is identical to a live run but no entries are created (created will always be 0 in the response when dry_run=true).

---

GET /api/v1/admin/models/{id}

Retrieve a single model registry entry by UUID.

Path Parameters

Parameter	Type	Description
id	UUID	Model registry entry UUID

Response

200 OK — full model entry object (same schema as list items).

Error Codes

Code	Error	Description
404 Not Found	model_not_found	No entry with the given UUID

---

PUT /api/v1/admin/models/{id}

Update a model registry entry. All fields are optional — only provided fields are updated (partial update semantics).

Request Body

{
  "risk_tier": "tier_1",
  "validation_status": "validated",
  "owner": "platform-security-team",
  "tags": ["production", "critical", "high-risk"]
}

All fields from the create schema are accepted. model_id and provider cannot be changed after creation.

Tag semantics: tags is a replace operation — the provided array completely replaces the existing tag list. To add a tag, include all existing tags plus the new one.

Response

200 OK — updated model entry.

Error Codes

Code	Error	Description
404 Not Found	model_not_found	No entry with the given UUID
422 Unprocessable	invalid_status_transition	The requested validation_status transition is not permitted

Valid Status Transitions

The validation lifecycle follows a defined state machine. Invalid transitions return 422 invalid_status_transition.

draft
  → pending_validation
  → in_validation
  → validated
  → deprecated

in_validation
  → needs_remediation
  → validated

needs_remediation
  → in_validation
  → deprecated

validated
  → deprecated

deprecated
  (terminal — no transitions)

Every status update generates an audit event recording the previous status, new status, and the admin user who made the change.

---

DELETE /api/v1/admin/models/{id}

Remove a model registry entry.

Path Parameters

Parameter	Type	Description
id	UUID	Model registry entry UUID

Response

204 No Content — deletion successful.

Cascade Behavior

Deleting a registry entry does not cascade to audit log records — historical audit log entries that reference this model_id are preserved. Audit log records use the model_id string directly, not a foreign key to the registry.

After deletion, the model ID is treated as unregistered by the policy engine. The model_risk_tier condition in policy rules evaluates unregistered models using the unregistered_model_tier default (configured in org settings, default tier_4).

Error Codes

Code	Error	Description
404 Not Found	model_not_found	No entry with the given UUID

---

GET /api/v1/admin/model-inventory-export

Export the full model registry as a downloadable file.

Query Parameters

Parameter	Type	Description
format	string	Export format: csv or json (default: json)
risk_tier	string	Filter by risk tier (optional)
validation_status	string	Filter by validation status (optional)
provider	string	Filter by provider (optional)

Response

JSON format (Content-Type: application/json):

[
  {
    "id": "3fa85f64-...",
    "model_id": "gpt-4o",
    "provider": "openai",
    "display_name": "GPT-4o",
    "risk_tier": "tier_2",
    "validation_status": "validated",
    "owner": "ml-platform-team",
    "description": "...",
    "tags": ["production"],
    "request_count_30d": 142857,
    "first_seen_at": "2026-01-15T09:30:00Z",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-03-01T14:22:00Z"
  }
]

CSV format (Content-Type: text/csv, Content-Disposition: attachment; filename="model-inventory.csv"):

Column	Description
id	UUID
model_id	Canonical model identifier
provider	Provider name
display_name	Human-readable name
risk_tier	OCC SR 11-7 risk tier
validation_status	Lifecycle validation status
owner	Responsible team
description	Free-text description
tags	Pipe-separated tag list
request_count_30d	Request count (30-day rolling)
first_seen_at	ISO 8601 timestamp
created_at	ISO 8601 timestamp
updated_at	ISO 8601 timestamp

Example

# Export all models as CSV for SR 11-7 model inventory documentation
curl "https://your-platform/api/v1/admin/model-inventory-export?format=csv" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -o model-inventory.csv

# Export only unvalidated models as JSON for remediation tracking
curl "https://your-platform/api/v1/admin/model-inventory-export?format=json&validation_status=needs_remediation" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

---

Data Model Reference

Risk Tiers (OCC SR 11-7)

Value	Description
tier_1	Critical — systemic or enterprise-wide decision making
tier_2	High — significant business decisions, customer-facing
tier_3	Moderate — operational support, limited scope
tier_4	Low — informational, human-reviewed output
unclassified	Not yet assessed (default for new/discovered models)

Validation Statuses

Value	Description
draft	Initial entry, not yet submitted for validation
pending_validation	Submitted — awaiting validator assignment
in_validation	Actively under review
validated	Approved for use
needs_remediation	Validation failed — requires fixes before re-review
deprecated	Retired from use — terminal state
unclassified	Status unknown (auto-discovery default)

---

Related

• Model Risk Management Guide — OCC SR 11-7 workflow and governance process
• Policy Engine — model_risk_tier condition for policy rules
• Compliance Frameworks — regulatory bundle configuration
• Audit Log Management — querying audit records by model ID