Dry-Run Sessions API¶

Stateful conversation sessions for testing agents interactively. Sessions maintain context across messages, support persona switching, and optionally use cross-session memory via AWS Bedrock.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token Prefix: /dry-run/sessions

Session Lifecycle¶

stateDiagram-v2
    [*] --> Active: POST /start
    Active --> Active: POST /{token}/message
    Active --> Active: PUT /{token}/persona
    Active --> Active: POST /{token}/reset
    Active --> Ended: POST /{token}/end
    Active --> Expired: TTL exceeded
    Ended --> [*]
    Expired --> [*]

Endpoints¶

List Active Sessions¶

GET /dry-run/sessions

Returns up to 20 active sessions, ordered by last interaction.

Response:

{
  "success": true,
  "sessions": [
    {
      "token": "drs_abc123def456",
      "persona": "buyer",
      "entity_type": "AiPresentation",
      "entity_title": "Q1 Product Launch Deck",
      "message_count": 5,
      "started_at": "2026-02-26T10:00:00Z",
      "last_interaction_at": "2026-02-26T10:15:00Z"
    }
  ]
}

Start Session¶

POST /dry-run/sessions/start

Parameter	Type	Required	Default	Description
`entity_type`	string	Yes	—	`ai_presentation`, `ai_proposal`, or `ai_cosell`
`entity_id`	integer	Yes	—	ID of the entity to provide context
`persona`	string	Yes	—	Agent persona (e.g., `buyer`, `technical_reviewer`)
`use_bedrock_memory`	boolean	No	`true`	Enable cross-session memory
`quality`	string	No	`standard`	`quick`, `standard`, or `detailed`

Response:

{
  "success": true,
  "session": {
    "token": "drs_abc123def456",
    "persona": "buyer",
    "expires_at": "2026-02-26T12:00:00Z",
    "messages": [
      {
        "role": "assistant",
        "content": "I'm ready to help you explore this listing. What would you like to know?"
      }
    ],
    "message_count": 1
  }
}

Send Message¶

POST /dry-run/sessions/{token}/message

Parameter	Type	Required	Max Length	Description
`message`	string	Yes	10,000 chars	User message or query

Response:

{
  "success": true,
  "response": "Based on the knowledge base, AWS Marketplace pricing supports three models...",
  "metadata": {
    "model": "claude-3-sonnet",
    "knowledge_sources_used": ["user-kb", "platform-kb"],
    "tokens_used": 1250
  },
  "session": {
    "token": "drs_abc123def456",
    "persona": "buyer",
    "message_count": 3
  }
}

Get Session Details¶

GET /dry-run/sessions/{token}

Returns full session state including all messages, persona configuration, and context snapshot.

Response:

{
  "success": true,
  "session": {
    "token": "drs_abc123def456",
    "persona": "buyer",
    "persona_config": {},
    "is_active": true,
    "expires_at": "2026-02-26T12:00:00Z",
    "started_at": "2026-02-26T10:00:00Z",
    "last_interaction_at": "2026-02-26T10:15:00Z",
    "messages": [],
    "message_count": 5,
    "context": {}
  }
}

Switch Persona¶

PUT /dry-run/sessions/{token}/persona

Change the agent's persona mid-session without losing conversation history.

Parameter	Type	Required	Description
`persona`	string	Yes	New persona name

Reset Session¶

POST /dry-run/sessions/{token}/reset

Clear all messages and start fresh while keeping the same session token and entity context.

Response:

{
  "success": true,
  "message": "Session reset successfully. The buyer persona has fresh eyes on your content.",
  "session": {
    "token": "drs_abc123def456",
    "persona": "buyer",
    "message_count": 0
  }
}

End Session¶

POST /dry-run/sessions/{token}/end

Terminate the session and clean up resources.

Use Cases¶

Test a Sales Presentation¶

Start a session: POST /dry-run/sessions/start with entity_type: "ai_presentation" and persona: "buyer"
Ask questions from the buyer's perspective: POST /dry-run/sessions/{token}/message
Switch to technical reviewer: PUT /dry-run/sessions/{token}/persona
Ask technical questions to find gaps
End the session: POST /dry-run/sessions/{token}/end

Iterative Content Refinement¶

Start a session with a co-sell proposal: entity_type: "ai_cosell"
Send a review request: "What are the weaknesses in this proposal?"
Refine based on feedback, send follow-ups
Reset to get fresh perspective: POST /dry-run/sessions/{token}/reset
Re-evaluate with the refined content

Multi-Persona Evaluation¶

Start with persona: "buyer" — ask about value proposition
Switch to persona: "technical_reviewer" — probe technical details
Switch to persona: "executive" — evaluate business impact
Each persona brings a different evaluation lens to the same content