{"openapi": "3.1.0", "info": {"title": "Architect Evolution Engine API", "version": "0.1.0", "description": "MVP engine surface for candidate lifecycle, review, publication, continuation, run capture, retrieval, and bridge health."}, "servers": [{"url": "http://127.0.0.1:8000"}], "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "token"}}}, "security": [{"bearerAuth": []}], "paths": {"/bridge/status": {"get": {"summary": "Bridge status", "description": "Read bridge mode, health, auth status, and capability set.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/system/status": {"get": {"summary": "System status", "description": "Fetch a compact engine status summary and recommended next action.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/openapi.json": {"get": {"summary": "OpenAPI document", "description": "Fetch the current OpenAPI export for bridge/action configuration.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/openai/status": {"get": {"summary": "OpenAI assistive status", "description": "Fetch OpenAI assistive analysis configuration status.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/metrics/summary": {"get": {"summary": "Metrics summary", "description": "Fetch the current MVP metrics summary.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/reports/phase1/acceptance": {"get": {"summary": "Phase 1 acceptance report", "description": "Fetch the current Phase 1 acceptance report.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/reports/phase1/exit": {"get": {"summary": "Phase 1 exit report", "description": "Fetch the current Phase 1 exit report.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/reports/phase2/readiness": {"get": {"summary": "Phase 2 readiness report", "description": "Fetch the current Phase 2 readiness report.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/runs/events": {"post": {"summary": "Create run event", "description": "Persist a run event for traceable engine capture.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/runs/{run_id}/events": {"get": {"summary": "List run events", "description": "List run events for a captured run.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/role-records/{role_type}": {"post": {"summary": "Upsert role record", "description": "Create or replace a role-scoped record for the run.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/runs/{run_id}/role-records": {"get": {"summary": "List role records", "description": "List role records for the run, optionally filtered by role type.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/runs/{run_id}/evolution-events": {"get": {"summary": "List evolution events", "description": "List engine evolution events for the run.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/events/recent": {"get": {"summary": "List recent events", "description": "List recent run and evolution events across recent runs.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/analysis/handoff": {"post": {"summary": "Analyze handoff", "description": "Analyze framework-to-logic handoff state and create candidates.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/analysis/handoff/assist": {"post": {"summary": "Assistive handoff diagnosis", "description": "Use OpenAI as an assistive diagnosis layer for handoff analysis without creating canonical state.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/chat/conversations": {"get": {"summary": "List chat conversations", "description": "List stored operator chat conversations.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}, "post": {"summary": "Create chat conversation", "description": "Create a new stored chat conversation.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/chat/conversations/{conversation_id}": {"get": {"summary": "Get chat conversation", "description": "Fetch a stored chat conversation and its messages.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/chat/conversations/{conversation_id}/rename": {"post": {"summary": "Rename chat conversation", "description": "Rename a stored chat conversation.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/chat/conversations/{conversation_id}/archive": {"post": {"summary": "Archive chat conversation", "description": "Archive a stored chat conversation so it leaves the main list.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/chat/conversations/{conversation_id}/restore": {"post": {"summary": "Restore chat conversation", "description": "Restore an archived chat conversation back into the main list.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/chat/conversations/{conversation_id}/messages": {"post": {"summary": "Send chat message", "description": "Create a user message, process it, and store the assistant reply.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/chat/attachments/{attachment_id}": {"get": {"summary": "Get chat attachment", "description": "Fetch an uploaded attachment from a chat conversation.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/queue": {"get": {"summary": "Review queue", "description": "List queue-ready candidates with filtering support.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/candidates": {"get": {"summary": "List candidates", "description": "List candidates, optionally filtered by state.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}, "post": {"summary": "Create candidate", "description": "Create a candidate and optionally elevate it to evidence_ready.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/candidates/{candidate_id}": {"get": {"summary": "Get candidate", "description": "Fetch a candidate by identifier.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/candidates/{candidate_id}/status": {"get": {"summary": "Candidate status", "description": "Read current candidate status and terminal posture.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/candidates/{candidate_id}/traceability": {"get": {"summary": "Candidate traceability", "description": "Fetch candidate traceability summary.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/candidates/{candidate_id}/detail": {"get": {"summary": "Candidate detail", "description": "Read operator detail for a candidate, including evidence and acceptance checks.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/candidates/{candidate_id}/review-readiness": {"get": {"summary": "Review readiness", "description": "Read review readiness and blockers for a candidate.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/candidates/{candidate_id}/publication-status": {"get": {"summary": "Publication status", "description": "Read candidate publication completeness/correction posture.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/reviews/submit": {"post": {"summary": "Submit review decision", "description": "Submit an operator review decision using decision_timestamp.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/reviews/{review_decision_id}": {"get": {"summary": "Get review decision", "description": "Fetch a review decision by identifier.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/publications/request": {"post": {"summary": "Request publication", "description": "Request publication for an approved candidate.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/publications/{publication_id}": {"get": {"summary": "Get publication", "description": "Fetch publication completion details.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/assets": {"get": {"summary": "List assets", "description": "List published assets with optional filters.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/assets/{asset_id}": {"get": {"summary": "Get asset", "description": "Fetch published asset detail and linked change logs.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/assets/{asset_id}/change-logs": {"get": {"summary": "List change logs", "description": "List change logs for a published asset.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/notes": {"get": {"summary": "List operator notes", "description": "List governed operator notes with optional target/run filters.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}, "post": {"summary": "Store operator note", "description": "Store a governed operator note in engine storage.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/continuation/{candidate_id}": {"get": {"summary": "Get continuation state", "description": "Fetch latest continuation state for a candidate.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/continuation/session/{session_id}": {"get": {"summary": "List session continuation", "description": "List continuation state items for the current interaction session.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/continuation/update": {"post": {"summary": "Update continuation state", "description": "Store or refresh continuation state through the engine.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/operator/queue": {"get": {"summary": "Operator queue page", "description": "HTML queue view for operators.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/operator/chat": {"get": {"summary": "Operator chat page", "description": "HTML chat shell with stored conversations and uploads.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/operator/candidates/{candidate_id}": {"get": {"summary": "Operator candidate detail page", "description": "HTML candidate detail view.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/operator/assets": {"get": {"summary": "Operator assets page", "description": "HTML asset library view.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/operator/assets/{asset_id}": {"get": {"summary": "Operator asset detail page", "description": "HTML asset detail view.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/operator/metrics": {"get": {"summary": "Operator metrics page", "description": "HTML metrics dashboard view.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}, "/operator/reports": {"get": {"summary": "Operator reports page", "description": "HTML acceptance/readiness report view.", "responses": {"200": {"description": "Successful response"}, "201": {"description": "Created"}, "400": {"description": "Validation or workflow error"}, "401": {"description": "Unauthorized"}, "403": {"description": "Insufficient scope"}}}}}}