AI Preview API

API: AI Preview

Admin authentication: administrator JWT/session. Role: admin.

Advisory only. recommendation_only is true on status. EnforcementApplied is not a live apply path. There is no apply-rule AI route. Human approval is required when AI is enabled.

Additional internal AI development endpoints exist in Enterprise source and are not part of AI Preview. Detailed credential custody procedures are provided separately to Enterprise customers (local envelope; no training export).

GET /api/v1/ai/status #

Purpose. Preview readiness and bounds.

Authentication. Admin.

Parameters. None.

Request. Empty.

Example request.

curl -sS https://manager.example.com:8443/api/v1/ai/status \
  -H "Authorization: Bearer TOKEN"Copy

Response (200).

{
  "success": true,
  "message": "AI status retrieved",
  "data": {
    "enabled": false,
    "configured": false,
    "provider": "openai_compatible",
    "model": "",
    "mode": "disabled",
    "offline_mode": true,
    "redaction_enabled": true,
    "require_human_approval": true,
    "recommendation_only": true,
    "model_calls_from_browser": false,
    "manager_readiness_depends_on_ai": false
  }
}Copy

AIStatusResponse also includes last_success_at, last_error_code, last_error_class, last_error_at, redaction_version, prompt_template_versions, output_schema_versions, counters, latency, token_usage. Unknown providers are normalized to "unknown". Only openai_compatible is a supported provider class.

Errors. 200 even when disabled. Entitlement may force enabled/configured false.

Edition. ENTERPRISE_ONLY.

Security. Status does not return API keys. Manager readiness does not depend on AI.

GET /api/v1/ai/providers #

GET /api/v1/ai/providers/:id #

POST /api/v1/ai/providers #

PATCH /api/v1/ai/providers/:id #

POST /api/v1/ai/providers/:id/retire #

POST /api/v1/ai/providers/:id/test-connection #

POST /api/v1/ai/providers/:id/manual-eligibility #

Purpose. Register OpenAI-compatible endpoints. Saving a provider does not start analysis and does not store a key in the browser.

Authentication. Admin.

Create/update request. Provider draft fields include display_name, provider_class, api_protocol, base_url, model_id, timeout/byte/token limits. API_SCHEMA_DOCUMENTATION_BLOCKED for every optional nested policy field not copied from aiProviderResponse — create bind is a large handler struct.

Documented response (aiProviderResponse): id, display_name, provider_class, api_protocol, base_url, model_id, model_artifact_id, endpoint_policy_class, registration/credential/manual/automatic/experiment/health/circuit states, capabilities, limits, retain_raw_request / retain_raw_response, IP policies, provider_training, last test fields.

Retire: {"expected_version": <int64>}. Manual eligibility: expected_version, enabled. Test-connection: confirmed, optional ephemeral_credential (secret; not logged).

Edition. ENTERPRISE_ONLY.

Security. provider_training must remain consistent with ai.training_export.enabled (must be false for customer Preview). Ephemeral test credentials are not persisted as browser storage.

POST /api/v1/ai/manual-analysis/preview #

GET /api/v1/ai/manual-analysis/credential-options #

GET /api/v1/ai/manual-analysis/:request_id #

POST /api/v1/ai/manual-analysis/:request_id/execute #

POST /api/v1/ai/manual-analysis/:request_id/cancel #

Purpose. Operator-triggered analysis with explicit acknowledgements.

Authentication. Admin.

Preview request (manualPreviewRequest): client_request_id, selections[] (security_log_id and/or analysis_id), provider_id, model_id, privacy_policy, retention_mode, exact_ip_acknowledged, credential_source.

Execute request (manualExecuteRequest): confirmation_token, optional ephemeral_credential, reviewed_data_categories, provider_retention_acknowledged, advisory_only_acknowledged, cost_bound_acknowledged, exact_ip_acknowledged.

Transient result (manualTransientResult): run_id, group_id, source_security_log_id, status, retention_mode, classification/severity/confidence/summary, advisory_action, evidence, requires_human_review, usage tokens, advisory_only: true, enforcement_applied: false.

Edition. ENTERPRISE_ONLY.

Security. Acknowledgements are required. Do not send production event payloads to unapproved providers.

GET /api/v1/ai/comparisons #

GET /api/v1/ai/comparisons/:group_id #

GET /api/v1/ai/comparison-runs/:run_id #

Purpose. Comparison groups for manual runs.

Authentication. Admin.

Response. API_SCHEMA_DOCUMENTATION_BLOCKED for nested comparison maps — list handlers return domain comparison objects inside V1-like envelopes.

Edition. ENTERPRISE_ONLY.

GET /api/v1/ai/recommendations #

GET /api/v1/ai/recommendations/:id #

GET /api/v1/ai/recommendations/:id/lineage #

POST /api/v1/ai/recommendations/:id/approve #

POST /api/v1/ai/recommendations/:id/reject #

Purpose. Unpublished recommendations. Approve/reject is governance only.

Authentication. Admin.

Decision body (AIRecommendationDecisionRequest): {"reason":"..."}.

Response. Recommendation projection (AIRecommendationResponse family). Explain helper: AIExplainSecurityLogResponse (log_id, summary, explanation, severity, recommended_actions, false_positive_checks, recommendation_only, model, redaction_status).

Edition. ENTERPRISE_ONLY.

POST /api/v1/ai/recommendation-drafts/preview #

POST /api/v1/ai/recommendation-drafts/confirm #

Purpose. Draft preview/confirm (recommendationPreviewRequest.sources, recommendationConfirmRequest.confirmation_token + preview_hash).

Authentication. Admin.

Edition. ENTERPRISE_ONLY.

POST /api/v1/ai/security-logs/:id/explain #

Purpose. Explain one stored security log. Advisory text only.

Authentication. Admin.

Parameters. :id integer log id.

Request. Empty or ignored extras.

Response. AIExplainSecurityLogResponse inside success envelope. 400 Invalid security log ID.

Edition. ENTERPRISE_ONLY.

POST /api/v1/ai/incidents/analyze #

Purpose. Analyze selected log ids (AIAnalyzeIncidentRequest.log_ids).

Authentication. Admin.

Response. Advisory incident analysis. API_SCHEMA_DOCUMENTATION_BLOCKED for the full output object beyond advisory fields on explain/transient result.

Edition. ENTERPRISE_ONLY.

POST /api/v1/ai/rules/draft #

POST /api/v1/ai/rule-drafts #

GET /api/v1/ai/rule-drafts/:id #

PUT /api/v1/ai/rule-drafts/:id #

Purpose. Unpublished rule drafts (AIRuleDraftRequest: log_ids, intent, persist_recommendation). Saving a draft does not call POST /api/v1/rules.

Authentication. Admin.

Edition. ENTERPRISE_ONLY.

GET /api/v1/ai/operations/status #

GET /api/v1/ai/operations/alerts #

POST /api/v1/ai/operations/alerts/:id/acknowledge #

POST /api/v1/ai/operations/alerts/:id/resolve #

Purpose. Preview operations alerts (not internal AI development control-plane).

Authentication. Admin.

Alert action body: expected_record_version, reason.

Edition. ENTERPRISE_ONLY.

GET /api/v1/ai/source-events/security-logs/:id #

Purpose. Source-event projection for an analysis (redacted categories).

Authentication. Admin.

Response. API_SCHEMA_DOCUMENTATION_BLOCKED — projection maps without a stable public DTO.

Edition. ENTERPRISE_ONLY.

Credential custody #

Prefix /api/v1/ai/credential-custody/. Local envelope custody. Training export must stay disabled.

Documented bind structs: custodyProfileDraftRequest, custodyBindingDraftRequest, custodyTransitionRequest, credentialEnrollmentRequest (credential secret bytes), rotation/destroy (confirm_destroy).

List/get/approve/disable/retire/readiness/enroll/rotate/rewrap/revoke-material/destroy-material as in inventory.

Do not return raw key material in examples. API_SCHEMA_DOCUMENTATION_BLOCKED for backend-health maps.

Edition. ENTERPRISE_ONLY.

Security. Keys never in YAML for production; systemd/local envelope only. Custody details are provided separately to Enterprise customers.

Related #

• AI Preview status
• Operator control