Architect Sessions API

Last verified against the implementation on 2026-03-16.

The Architect Sessions API drives the full Project Architect workflow: session creation, analysis, clarification, proposal generation, rejection, acceptance, and Studio transfer.

Endpoints

Method	Path	Purpose
POST	/api/v1/architect/sessions	Create a session
GET	/api/v1/architect/sessions	List company sessions
GET	/api/v1/architect/sessions/:id	Fetch session detail
PATCH	/api/v1/architect/sessions/:id	Update title or requirements
DELETE	/api/v1/architect/sessions/:id	Delete a session
POST	/api/v1/architect/sessions/:id/analyze	Run requirements analysis
POST	/api/v1/architect/sessions/:id/dialogue	Submit clarification answers
POST	/api/v1/architect/sessions/:id/generate	Generate a proposal
GET	/api/v1/architect/sessions/:id/proposal	Fetch the stored proposal
POST	/api/v1/architect/sessions/:id/reject	Persist a rejected proposal
POST	/api/v1/architect/sessions/:id/accept	Provision VeriPrompt resources
POST	/api/v1/architect/sessions/:id/transfer	Resolve or create the linked Studio project

Authentication

• Uses the standard authenticated VeriPrompt web session.
• All routes are scoped to the signed-in user's companyId.
• The :id route parameter is the database ArchitectSession.id, not the public arch_* sessionId.

Session Lifecycle

INPUT -> ANALYZING -> DIALOGUE -> GENERATING -> PROPOSAL_READY -> ACCEPTED
                                                        |
                                                        -> REJECTED

State enforcement:

• PATCH only works in INPUT or DIALOGUE.
• analyze requires INPUT.
• dialogue requires DIALOGUE.
• generate requires DIALOGUE or GENERATING.
• reject requires PROPOSAL_READY.
• accept requires PROPOSAL_READY.
• transfer accepts ACCEPTED and auto-accepts PROPOSAL_READY.

Create Session

POST /api/v1/architect/sessions

Creates a new session in INPUT.

Example body:

{
  "title": "Claims Intake Automation",
  "requirements": {
    "description": "Build an AI claims intake workflow for insurance adjusters.",
    "industry": "Insurance",
    "useCase": "Claims Intake Automation",
    "securityLevel": "high",
    "providers": ["OPENAI"],
    "targetFramework": "langchain",
    "frameworkDetails": "LangChain workers calling VeriPrompt MCP tools"
  }
}

Rules:

• requirements.description or requirements.fileContent must be present.
• securityLevel must be one of basic, standard, high, critical.

Success:

• 201 Created
• Returns { success: true, session }

List Sessions

GET /api/v1/architect/sessions

Query params:

• status: ALL, INPUT, ANALYZING, DIALOGUE, GENERATING, PROPOSAL_READY, ACCEPTED, REJECTED
• limit: 1 to 100
• offset: 0+

Returns sessions plus pagination.

Get Session

GET /api/v1/architect/sessions/:id

Returns the stored workflow record, including requirements, gaps, proposal, generated resource ids, and user metadata.

Update Session

PATCH /api/v1/architect/sessions/:id

Supported fields:

• title
• requirements

Updating requirements clears prior analysis, dialogue, proposal, and generated ids, then resets the session to INPUT.

Delete Session

DELETE /api/v1/architect/sessions/:id

Hard-deletes the session if it belongs to the same company.

Analyze Requirements

POST /api/v1/architect/sessions/:id/analyze

Runs the first AI pass and stores:

• gaps.analysis
• gaps.questions
• quickWins
• decisions
• conflicts

Important behavior:

• Architect now performs provider preflight before calling the internal gateway.
• If no healthy matching provider is available, the route returns 503.
• If the model returns malformed JSON, Architect falls back to a minimal analysis object instead of failing immediately.
• On success the session moves to DIALOGUE.

Common responses:

• 200 analysis stored
• 400 invalid state
• 404 session not found
• 503 provider preflight failed

Submit Dialogue Answers

POST /api/v1/architect/sessions/:id/dialogue

Example body:

{
  "answers": {
    "q_1": "Escalate high-risk cases to a human review queue."
  }
}

Behavior:

• Validates that at least one answer exists.
• Enforces DIALOGUE state.
• Runs provider preflight before the refinement round-trip.
• Returns status: "DIALOGUE" if more clarification is needed.
• Returns status: "GENERATING" if proposal generation can proceed.

Common responses:

• 200 answers recorded
• 400 invalid body or invalid state
• 404 session not found
• 503 provider preflight failed

Generate Proposal

POST /api/v1/architect/sessions/:id/generate

Generates and validates a proposal containing prompts, routing policy, MCP architecture, skills architecture, reference-library metadata, and an implementation guide.

Validation includes:

• meaningful projectDescription
• at least 3 prompts
• populated implementation-guide sections
• MCP-enabled prompts and tool metadata when agentic frameworks require them
• skill metadata for SKILL prompts

Responses:

• 200 proposal stored and session moved to PROPOSAL_READY
• 400 invalid state
• 404 session not found
• 422 proposal output was incomplete and failed scaffold validation
• 503 provider preflight failed

If validation fails, Architect moves the session back to DIALOGUE and stores the issues in conflicts.qualityIssues.

Get Proposal

GET /api/v1/architect/sessions/:id/proposal

Returns:

• proposal
• status
• provisioned metadata if the session is already ACCEPTED

If no proposal exists yet, the route returns 400.

Reject Proposal

POST /api/v1/architect/sessions/:id/reject

Requires PROPOSAL_READY.

Optional body:

{
  "reason": "The implementation scope is too broad for the current release."
}

Behavior:

• Sets the session status to REJECTED
• Stores rejection metadata in dialogueHistory
• Writes an ARCHITECT_REJECT_PROPOSAL audit log entry

Responses:

• 200 proposal rejected
• 400 session is not PROPOSAL_READY
• 404 session not found

Accept Proposal

POST /api/v1/architect/sessions/:id/accept

Requires PROPOSAL_READY.

On success, Architect provisions:

• Project
• RoutingPolicy
• StoredPrompt records
• initial prompt versions
• PromptVariable records
• a project-bound ReferenceLibrary
• generated scaffold ReferenceDocument records
• prompt-library bindings
• an audit log entry

The current implementation always creates a reference library during accept.

Transfer To Studio

POST /api/v1/architect/sessions/:id/transfer

Behavior:

• If the session is already ACCEPTED, returns the linked Studio project.
• If the session is PROPOSAL_READY, Architect auto-accepts it first, then returns the linked project.

The /architect/transfer UI lists both ACCEPTED and PROPOSAL_READY sessions.

Verification Summary

Verified live on 2026-03-16:

• create, list, detail, update, delete
• analyze
• dialogue success and validation failure
• generate invalid-state guard
• reject success path
• legacy transfer and architect UI routing
• transfer UI listing for PROPOSAL_READY

Not fully verified to successful completion in the current local environment:

• generate success path
• accept success path
• transfer success path

Reason:

• the local provider setup still produced incomplete proposal output, so generation returned scaffold-quality errors before PROPOSAL_READY could be reached naturally.

Related Docs

• Project Architect Feature