Skip to main content

Media Governance Configuration API

The Media Governance Configuration API allows you to check feature availability, retrieve the current media governance settings, and update per-tenant configuration. These endpoints are served by the Orchestrator on port 8081 and are commonly reached through the Agent proxy.

For background on media governance concepts such as analyzers, system policies, and multimodal governance, see Media Governance.

Authentication​

When you call these endpoints through the Agent proxy (port 8080), authenticate with Basic auth using your client ID and client secret. The Agent validates the credentials and injects the tenant-scoping headers before forwarding to the Orchestrator:

curl http://localhost:8080/api/v1/media-governance/status \
  -H "Authorization: Basic $(echo -n 'your-client-id:your-client-secret' | base64)"

Header compatibility: the config handlers resolve the tenant from the X-Tenant-ID header first, falling back to X-Org-ID (backward-compatible). Through the Agent proxy both are set automatically from the authenticated client, and any client-supplied values are overwritten. Only callers hitting the Orchestrator directly need to set the header themselves. See the Auth And Header Matrix for the full header model.

All three routes also accept OPTIONS for CORS preflight.

Tier Restrictions​

The update handler checks for a paid self-hosted tier in code (Professional, Enterprise, or Plus). In practice that means community and evaluation can read status and config, while paid deployments get per-tenant write control.

CapabilityCommunityEvaluationPaid tiers
Get feature statusYesYesYes
Get media governance configYesYesYes
Enable or disable media governance per tenantNoNoYes
Restrict allowed analyzers per tenantNoNoYes

Community and evaluation still have meaningful value here because they can confirm feature availability and understand the operational model before enabling more granular per-tenant controls in enterprise deployments. On non-paid tiers, media governance can still be switched on platform-wide with the MEDIA_GOVERNANCE_ENABLED environment variable (true or 1) — the env var is the community opt-in, while the API is the paid per-tenant control.

Endpoints​

GET /api/v1/media-governance/status​

Returns the media governance feature availability for the deployment's tier. This endpoint does not require a tenant header.

Response (200):

{
  "available": true,
  "enabled_by_default": true,
  "per_tenant_control": true,
  "tier": "Enterprise"
}
FieldTypeDescription
availablebooltrue when media governance is active — either the tier enables it by default or the MEDIA_GOVERNANCE_ENABLED env var override is set
enabled_by_defaultboolWhether the deployment's tier enables media governance by default
per_tenant_controlbooltrue on paid tiers (Professional, Enterprise, Plus), where PUT /config is available
tierstringThe deployment's license tier

GET /api/v1/media-governance/config​

Returns the current media governance configuration for the tenant identified by X-Tenant-ID (or X-Org-ID). When no per-tenant row exists yet, the handler returns a default config whose enabled value follows the tier default (or the MEDIA_GOVERNANCE_ENABLED env override).

Response (200):

{
  "tenant_id": "tenant-123",
  "enabled": true,
  "allowed_analyzers": ["pii", "content-moderation"],
  "updated_at": "2026-07-01T12:00:00Z",
  "updated_by": "[email protected]"
}
FieldTypeDescription
tenant_idstringTenant the config applies to
enabledboolWhether media governance is enabled for this tenant
allowed_analyzers[]stringAnalyzer allowlist; omitted when unrestricted
updated_attimestampLast update time
updated_bystringUser that last updated the config (from X-User-ID); omitted when never updated

Error Responses:

HTTP StatusCodeDescription
400MISSING_TENANT_IDNo X-Tenant-ID (or X-Org-ID) header on the request
500INTERNAL_ERRORConfig lookup failed

PUT /api/v1/media-governance/config​

Updates the media governance configuration for the tenant identified by X-Tenant-ID (or X-Org-ID). Paid-tier only. The request body is capped at 1 MB. Fields you omit are left unchanged; the handler merges the update into the existing config (or the tier-default config when none exists) and returns the updated config with HTTP 200. updated_by is stamped from the X-User-ID header (system when absent).

Request Body:

FieldTypeRequiredDescription
enabledboolNoEnable or disable media governance for this tenant
allowed_analyzers[]stringNoRestrict which analyzers the tenant can use

Error Responses:

HTTP StatusCodeDescription
400MISSING_TENANT_IDNo X-Tenant-ID (or X-Org-ID) header on the request
400INVALID_REQUESTRequest body is not valid JSON (or exceeds the 1 MB cap)
403TIER_RESTRICTEDConfiguration updates are not available on your tier
500INTERNAL_ERRORConfig lookup or save failed

Requests that fail authentication at the Agent proxy are rejected there with 401 before reaching these handlers.

Example:

{
  "error": {
    "code": "TIER_RESTRICTED",
    "message": "Per-tenant media governance configuration requires an Enterprise license. Use the MEDIA_GOVERNANCE_ENABLED environment variable for platform-wide control."
  }
}

Operational Readiness Checklist​

Before relying on this page in a production rollout, pair it with the core operations docs:

Last updated on