Sessions

Sessions manage the back-and-forth when an intent needs clarification before it can be executed.

How Sessions Work

When you call /v1/run and the intent is ambiguous, the API creates a session and returns clarification questions. You submit answers, and the session either resolves to a preview or asks more questions.

Session Flow

POST /v1/run → clarification → POST /v1/session/{id} → preview (or more clarification)

Session Lifecycle

1. Create a Session

Sessions are created automatically when you call /v1/run:

Request

curl -X POST https://api.grimoire.run/v1/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partner_id": "YOUR_PARTNER_ID", "user_message": "Move my USDC to a better yield", "user_context": {"chain": "ethereum"}}'

If clarification is needed:

Response

{
  "ok": true,
  "type": "clarification",
  "state": "CLARIFYING",
  "session_id": "sess_abc123",
  "fields": [
    {
      "id": "venue",
      "label": "Preferred protocol",
      "input": "select",
      "required": true,
      "options": ["aave_v3", "morpho_blue"]
    },
    {
      "id": "amount",
      "label": "Amount of USDC to move",
      "input": "number",
      "required": true
    }
  ]
}

2. Submit Answers

Request

curl -X POST https://api.grimoire.run/v1/session/sess_abc123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "venue": "morpho_blue",
      "amount": 5000
    }
  }'

The response is either another clarification (if more info is needed) or a preview:

Response

{
  "ok": true,
  "type": "preview",
  "state": "PREVIEW_READY",
  "session_id": "sess_abc123",
  "preview": {
    "summary": "Move 5000 USDC from Aave to Morpho Blue",
    "warnings": []
  }
}

3. Check Session State

At any point, you can check the current state of a session:

Request

curl https://api.grimoire.run/v1/session/sess_abc123 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "ok": true,
  "session_id": "sess_abc123",
  "state": "PREVIEW_READY",
  "unresolved_fields": [],
  "latest_preview": {
    "summary": "Move 5000 USDC from Aave to Morpho Blue",
    "warnings": []
  },
  "latest_summary": "Moving 5000 USDC to Morpho Blue for better yield.",
  "expires_at": "2026-02-26T13:00:00Z",
  "version": 3
}

Session States

State	Meaning
`CREATED`	Session just created
`CLASSIFYING`	Analyzing the intent
`CLARIFYING`	Waiting for answers to unresolved fields
`BUILDING`	Generating the action plan
`VALIDATING`	Running policy and preview validation
`PREVIEW_READY`	Intent fully resolved, preview available
`EXPIRED`	Session TTL elapsed

Endpoints

Submit Clarification Answers

Endpoint

POST /v1/session/{id}

Field	Type	Description
`answers`	object	Key-value pairs matching the `id` of each clarification field
`message`	string	Optional free-text follow-up message
`stream`	boolean	Enable SSE streaming

Get Session State

Endpoint

GET /v1/session/{id}

Returns:

Current state
Unresolved fields
Latest preview or summary
TTL (session expiration)
Optimistic version number

Example Flow

User:  "Optimize my lending position"
API:   What protocol? What asset? What's your target?
User:  "Aave, USDC, maximize APY"
API:   How much USDC?
User:  "All of it, up to 50,000"
API:   → PREVIEW_READY with action plan

Each round of clarification narrows the intent until the plan is specific enough to simulate and validate.