{"openapi":"3.1.0","info":{"title":"Enterprise AI Enablement OS API","version":"1.0.0","summary":"Governed integration API for Enterprise AI Enablement OS","description":"A versioned integration façade over the platform's existing governed domains. API v1 requires Microsoft Entra enterprise authentication for protected operations, derives authorization from validated app-role claims, fails closed when distributed rate limiting is unavailable, and does not bypass Human Approval, Finance validation, tenant isolation, evidence integrity, or model-release separation of duties."},"servers":[{"url":"/api/v1","description":"Current deployment"}],"tags":[{"name":"Opportunities"},{"name":"Workflows"},{"name":"Agents"},{"name":"Evidence"},{"name":"Value"},{"name":"Model Releases"},{"name":"Contract"}],"paths":{"/openapi":{"get":{"tags":["Contract"],"summary":"Download the OpenAPI 3.1 contract","responses":{"200":{"description":"OpenAPI document"}}}},"/opportunities/analyze":{"post":{"tags":["Opportunities"],"summary":"Analyze an enterprise AI opportunity","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"opportunities:analyze","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["problem","market","functionName"],"properties":{"problem":{"type":"string","minLength":12,"maxLength":2000},"market":{"type":"string","minLength":2,"maxLength":80},"functionName":{"type":"string","minLength":2,"maxLength":80}},"additionalProperties":false}}}},"responses":{"200":{"description":"Structured opportunity analysis"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/workflows":{"get":{"tags":["Workflows"],"summary":"Read the tenant workflow snapshot","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"workflows:read","responses":{"200":{"description":"Versioned workflow snapshot"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/workflows/actions":{"post":{"tags":["Workflows"],"summary":"Invoke a governed workflow mutation","description":"The underlying workflow policy remains authoritative. The API façade cannot record Human Approval from demo identities or bypass action-specific RBAC.","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"workflows:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Required retry-correlation key. Domain writes remain protected by optimistic concurrency or non-overwrite object-key semantics; buyer deployments needing cross-instance exact-once replay should add a durable idempotency registry at the gateway or persistence layer."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedVersion"],"properties":{"expectedVersion":{"type":"integer","minimum":0,"description":"Optimistic-concurrency version required by the underlying governed domain."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Committed workflow mutation"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/agents/runs":{"post":{"tags":["Agents"],"summary":"Run the governed specialist-agent workflow","description":"Returns Server-Sent Events and always stops at accountable human review; agent output never records its own approval.","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"agents:run","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scenario"],"properties":{"scenario":{"type":"string","minLength":12,"maxLength":4000}},"additionalProperties":false}}}},"responses":{"200":{"description":"text/event-stream governed agent run"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/evidence":{"get":{"tags":["Evidence"],"summary":"Read and integrity-verify a governed evidence object","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"evidence:read","parameters":[{"name":"objectId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Evidence object bytes after SHA-256 integrity verification"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"tags":["Evidence"],"summary":"Store governed evidence and bind it to workflow state","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"evidence:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Required retry-correlation key. Domain writes remain protected by optimistic concurrency or non-overwrite object-key semantics; buyer deployments needing cross-instance exact-once replay should add a durable idempotency registry at the gateway or persistence layer."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedVersion"],"properties":{"expectedVersion":{"type":"integer","minimum":0,"description":"Optimistic-concurrency version required by the underlying governed domain."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Stored evidence artifact and updated workflow snapshot"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/value-ledger":{"get":{"tags":["Value"],"summary":"Read the governed Value Ledger","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"value:read","responses":{"200":{"description":"Versioned Value Ledger"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/value-ledger/actions":{"post":{"tags":["Value"],"summary":"Invoke a governed Value Ledger mutation","description":"Finance validation and role separation remain enforced by the underlying value-domain policy.","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"value:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Required retry-correlation key. Domain writes remain protected by optimistic concurrency or non-overwrite object-key semantics; buyer deployments needing cross-instance exact-once replay should add a durable idempotency registry at the gateway or persistence layer."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedVersion"],"properties":{"expectedVersion":{"type":"integer","minimum":0,"description":"Optimistic-concurrency version required by the underlying governed domain."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Committed Value Ledger mutation"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/model-releases":{"get":{"tags":["Model Releases"],"summary":"Read model/provider certification and release state","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"model-releases:read","responses":{"200":{"description":"Model release state and persistence posture"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"tags":["Model Releases"],"summary":"Certify or approve a model release","description":"AI Enablement certifies. A distinct Risk Reviewer subject approves a recent persisted PASS certification. API v1 cannot collapse those authorities.","security":[{"entraBearer":[]}],"x-enterprise-ai-scope":"model-releases:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Required retry-correlation key. Domain writes remain protected by optimistic concurrency or non-overwrite object-key semantics; buyer deployments needing cross-instance exact-once replay should add a durable idempotency registry at the gateway or persistence layer."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedVersion"],"properties":{"expectedVersion":{"type":"integer","minimum":0,"description":"Optimistic-concurrency version required by the underlying governed domain."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Updated model release state"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"entraBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Microsoft Entra access token validated against configured tenant, audience, RS256 signature and app-role claims. Client-credentials service principals are supported when assigned the appropriate application roles."}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}}},"responses":{"BadRequest":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"A valid Microsoft Entra bearer token is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Forbidden":{"description":"The validated principal lacks the required API scope/role or the deployment is in demo mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Conflict":{"description":"Optimistic-concurrency or integrity conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Request budget exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unavailable":{"description":"A required fail-closed enterprise control is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-enterprise-ai-scope-catalog":[{"scope":"opportunities:analyze","roles":["BUSINESS_OWNER","AI_ENABLEMENT"]},{"scope":"workflows:read","roles":["EXECUTIVE","BUSINESS_OWNER","AI_ENABLEMENT","RISK_REVIEWER"]},{"scope":"workflows:write","roles":["BUSINESS_OWNER","AI_ENABLEMENT","RISK_REVIEWER"]},{"scope":"agents:run","roles":["BUSINESS_OWNER","AI_ENABLEMENT"]},{"scope":"evidence:read","roles":["EXECUTIVE","BUSINESS_OWNER","AI_ENABLEMENT","RISK_REVIEWER"]},{"scope":"evidence:write","roles":["BUSINESS_OWNER","AI_ENABLEMENT","RISK_REVIEWER"]},{"scope":"value:read","roles":["EXECUTIVE","BUSINESS_OWNER","AI_ENABLEMENT","RISK_REVIEWER","FINANCE_PARTNER"]},{"scope":"value:write","roles":["BUSINESS_OWNER","AI_ENABLEMENT","FINANCE_PARTNER"]},{"scope":"model-releases:read","roles":["EXECUTIVE","BUSINESS_OWNER","AI_ENABLEMENT","RISK_REVIEWER","FINANCE_PARTNER"]},{"scope":"model-releases:write","roles":["AI_ENABLEMENT","RISK_REVIEWER"]}]}}