Session API

Use the Session API when your server needs explicit control over users, sessions, messages, and revisions. Every request is server-to-server and must include an API key.

Authorization: Bearer $ZIWEI_API_KEY
Content-Type: application/json

Create and associate a session

curl https://chat-api.iztro.com/v2/platform/sessions \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id":"user_42","model":"iztro-ziwei-v3"}'

The response uses session_id. Persist it if you need to resume this exact conversation.

Set model to iztro-ziwei-v3 for natal and long-range analysis, or iztro-qimen-v3 for one concrete event decision. For Qimen, pass the user's local ISO 8601 question time as current_datetime when sending the message:

The faster non-thinking path is the session default. To make the whole session use deep reasoning, add "reasoning_effort": "high" when creating it. You can override the session for an individual message, edit, or resend with the same standard field; send "none" or "low" to select the non-thinking path for that turn.

{
  "message": "Should I advance this partnership now? If so, when?",
  "reasoning_effort": "high",
  "current_datetime": "2026-07-20T14:30:00+08:00",
  "language": "en",
  "enable_iztro_call": true
}

See Models for model selection, prompt shape, public calculation names, and timing semantics.

language is a per-turn response setting for send, stream, edit, and resend operations. It accepts zh, en, ko, ja, or vi. Set it when the output must use one language without mixed source terms; omit it to follow the conversation language automatically.

The Session API intentionally exposes only durable conversation controls: model, reasoning effort, language, local question time, application instructions, and the hosted-tool switch. Sampling and developer-tool settings belong to SDK or Chat Completions requests. See the complete Model settings matrix.

User and session management

Operation	Method and path
List a user's sessions	GET /v2/platform/users/{external_user_id}/sessions?limit=20
Read one session	GET /v2/platform/sessions/{session_id}
Update session metadata	PATCH /v2/platform/sessions/{session_id}
Read all messages	GET /v2/platform/sessions/{session_id}/messages
Send a message	POST /v2/platform/sessions/{session_id}/messages
Stream a message	POST /v2/platform/sessions/{session_id}/messages/stream
Edit a message	POST /v2/platform/sessions/{session_id}/messages/{message_id}/edit
Resend a message	POST /v2/platform/sessions/{session_id}/messages/{message_id}/resend
Stream an edit	Add /stream to the edit path
Stream a resend	Add /stream to the resend path

Edit and resend

Editing creates a new revision from a changed user message. Resending keeps the user message and generates a new assistant response. Persist the returned revision_id and message_id before the next operation.

curl -X POST "https://chat-api.iztro.com/v2/platform/sessions/$SESSION_ID/messages/$MESSAGE_ID/edit" \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Please explain the conclusion with more evidence."}'

curl -X POST "https://chat-api.iztro.com/v2/platform/sessions/$SESSION_ID/messages/$MESSAGE_ID/resend" \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete and fork

Delete and fork are not currently public platform routes. Do not call undocumented endpoints. Implement application-level soft deletion by removing the session from your user-facing index, and wait for an official fork endpoint before promising server-side copies.