API Reference Batch 11 — Model Registry

This batch documents the model registry API endpoints introduced in platform-0056. The model registry stores metadata for all AI models in use, including OCC SR 11-7 risk tier classifications and validation status. See Model Risk Management for conceptual documentation.

Authentication

All endpoints require a valid Bearer token with role: admin:

Authorization: Bearer <jwt>

Model Registry

List models

GET /api/admin/models

Returns all registered models for the organization, ordered by created_at descending.

Query parameters:

Parameter	Type	Description
`risk_tier`	string	Filter by risk tier: `tier_1`, `tier_2`, `tier_3`, `tier_4`
`validation_status`	string	Filter by status: `draft`, `pending_validation`, `in_validation`, `needs_remediation`, `validated`, `deprecated`
`provider`	string	Filter by provider name (case-insensitive, partial match)
`search`	string	Full-text search across `model_id`, `display_name`, and `description`
`limit`	integer	Max results to return. Default: `50`. Max: `200`.
`offset`	integer	Pagination offset. Default: `0`.

Response 200 OK:

{
  "total": 14,
  "limit": 50,
  "offset": 0,
  "models": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "tenant_id": "org_abc",
      "model_id": "gpt-4o",
      "provider": "openai",
      "display_name": "GPT-4o",
      "risk_tier": "tier_2",
      "validation_status": "validated",
      "owner": "ml-risk-team@example.com",
      "description": "Primary production model for customer service workflows",
      "tags": {
        "business_unit": "retail_banking",
        "use_case": "customer_service"
      },
      "last_seen_at": "2026-03-12T23:00:00Z",
      "created_at": "2026-01-15T09:00:00Z",
      "updated_at": "2026-03-01T14:30:00Z"
    }
  ]
}

Create model

POST /api/admin/models

Request body:

{
  "model_id": "claude-3-5-sonnet-20241022",
  "provider": "anthropic",
  "display_name": "Claude 3.5 Sonnet (Oct 2024)",
  "risk_tier": "tier_2",
  "validation_status": "pending_validation",
  "owner": "ai-risk-team@example.com",
  "description": "Conversational model for internal knowledge base queries",
  "tags": {
    "business_unit": "operations",
    "environment": "production"
  }
}

Field	Type	Required	Description
`model_id`	string	Yes	Provider model identifier. Must be unique within the organization.
`provider`	string	Yes	AI vendor or infrastructure provider (e.g., `openai`, `anthropic`, `azure`, `self-hosted`).
`display_name`	string	No	Human-readable name. Defaults to `model_id`.
`risk_tier`	string	Yes	OCC SR 11-7 tier: `tier_1`, `tier_2`, `tier_3`, or `tier_4`.
`validation_status`	string	No	Initial validation state. Default: `draft`.
`owner`	string	No	Email address or team identifier for the accountable owner.
`description`	string	No	Free-text description of the model’s purpose.
`tags`	object	No	Key/value tags for filtering and policy targeting.

Response 201 Created:

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "tenant_id": "org_abc",
  "model_id": "claude-3-5-sonnet-20241022",
  "provider": "anthropic",
  "display_name": "Claude 3.5 Sonnet (Oct 2024)",
  "risk_tier": "tier_2",
  "validation_status": "pending_validation",
  "owner": "ai-risk-team@example.com",
  "description": "Conversational model for internal knowledge base queries",
  "tags": {
    "business_unit": "operations",
    "environment": "production"
  },
  "last_seen_at": null,
  "created_at": "2026-03-13T00:00:00Z",
  "updated_at": "2026-03-13T00:00:00Z"
}

Error responses:

Status	Code	Description
`400`	`validation_error`	Missing required fields or invalid enum value
`409`	`model_already_exists`	A model with this `model_id` already exists in the organization

Get model

GET /api/admin/models/{id}

Retrieve a single model registry entry by its UUID.

Path parameters:

Parameter	Description
`id`	Model registry entry UUID

Response 200 OK:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "tenant_id": "org_abc",
  "model_id": "gpt-4o",
  "provider": "openai",
  "display_name": "GPT-4o",
  "risk_tier": "tier_2",
  "validation_status": "validated",
  "owner": "ml-risk-team@example.com",
  "description": "Primary production model for customer service workflows",
  "tags": {
    "business_unit": "retail_banking",
    "use_case": "customer_service"
  },
  "last_seen_at": "2026-03-12T23:00:00Z",
  "created_at": "2026-01-15T09:00:00Z",
  "updated_at": "2026-03-01T14:30:00Z"
}

Error responses:

Status	Code	Description
`404`	`model_not_found`	No model with this ID exists in the organization

Update model

PUT /api/admin/models/{id}

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

Path parameters:

Parameter	Description
`id`	Model registry entry UUID

Request body:

{
  "risk_tier": "tier_1",
  "validation_status": "in_validation",
  "owner": "sr-ml-risk@example.com",
  "description": "Reclassified to Tier 1 after production impact review"
}

Field	Type	Description
`display_name`	string	Human-readable name
`risk_tier`	string	New risk tier: `tier_1`, `tier_2`, `tier_3`, `tier_4`
`validation_status`	string	New validation status
`owner`	string	Updated owner email or team ID
`description`	string	Updated description
`tags`	object	Replaces the entire tags map (not merged). Send existing tags you wish to keep.

Response 200 OK: Returns the updated model object (same schema as GET).

Audit note: All PUT operations generate an audit event with the changed fields recorded for OCC SR 11-7 change history.

Error responses:

Status	Code	Description
`400`	`validation_error`	Invalid field value
`404`	`model_not_found`	No model with this ID
`422`	`invalid_status_transition`	The requested validation_status transition is not permitted. See Model Risk Management for valid transitions.

Delete model

DELETE /api/admin/models/{id}

Remove a model from the registry. This does not prevent the model from being used — it only removes the registry entry. If the model is referenced by active model_risk_tier policy conditions, those conditions will evaluate the model as tier_4 (the default for unregistered models) after deletion.

Path parameters:

Parameter	Description
`id`	Model registry entry UUID

Response 204 No Content

Error responses:

Status	Code	Description
`404`	`model_not_found`	No model with this ID

Auto-discover models

POST /api/admin/models/discover

Scan the audit log for AI request events and create draft registry entries for any model identifier not already registered.

Request body:

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

Field	Type	Required	Description
`lookback_days`	integer	No	Days of audit history to scan. Default: `30`. Max: `365`.
`auto_assign_tier`	string	No	Risk tier for newly discovered models. Default: `tier_4`.
`dry_run`	boolean	No	If `true`, returns discovery results without creating entries. Default: `false`.

Response 200 OK:

{
  "discovered": 7,
  "created": 5,
  "existing": 2,
  "dry_run": false,
  "models": [
    {
      "model_id": "gpt-4o-mini",
      "provider": "openai",
      "status": "created",
      "validation_status": "draft",
      "risk_tier": "tier_4",
      "first_seen_at": "2026-02-14T10:23:00Z",
      "last_seen_at": "2026-03-12T18:45:00Z",
      "request_count_30d": 1243
    },
    {
      "model_id": "gpt-4o",
      "provider": "openai",
      "status": "existing",
      "validation_status": "validated",
      "risk_tier": "tier_2"
    }
  ]
}

Response field	Description
`discovered`	Total distinct model IDs found in audit logs
`created`	New registry entries created
`existing`	Models already in the registry (skipped)
`dry_run`	Whether this was a dry run
`models[].status`	`created` or `existing`
`models[].request_count_30d`	Number of audit events for this model in the lookback period
`models[].first_seen_at`	Earliest audit event for this model in the lookback period

Note: Newly created entries have validation_status: draft and provider inferred from the model ID format. Provider inference uses a built-in lookup table (OpenAI, Anthropic, Google, Cohere, Meta patterns). Unknown providers are set to unknown.

Export model inventory

GET /api/admin/model-inventory-export

Export the complete model registry as a CSV file. Intended for GRC platform import, OCC SR 11-7 examination submissions, and internal risk reporting.

Query parameters:

Parameter	Type	Description
`format`	string	Output format: `csv` or `json`. Default: `csv`.
`risk_tier`	string	Filter by tier (optional).
`validation_status`	string	Filter by validation status (optional).

Response 200 OK (CSV):

Content-Type: text/csv
Content-Disposition: attachment; filename="model-inventory-2026-03-13.csv"

CSV columns:

Column	Description
`id`	Registry entry UUID
`model_id`	Provider model identifier
`provider`	AI vendor
`display_name`	Human-readable name
`risk_tier`	OCC SR 11-7 tier (tier_1–tier_4)
`validation_status`	Current validation lifecycle state
`owner`	Accountable owner
`description`	Description
`tags`	JSON-serialized tag map
`last_seen_at`	Last audit event timestamp for this model
`created_at`	Registry entry creation timestamp
`updated_at`	Last modification timestamp

Response 200 OK (JSON): Returns the full model list in the same schema as GET /api/admin/models (no pagination — all records returned).

Model Risk Management — conceptual guide, risk tiers, validation workflow
Policy Engine Deep Dive — model_risk_tier condition type
API Reference Batch 10 — policy engine API endpoints

API Reference Batch 11 — Model Registry

API Reference Batch 11 — Model Registry

Authentication

Model Registry

List models

Create model

Get model

Update model

Delete model

Auto-discover models

Export model inventory

Related pages