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.

For Ziwei, set model to iztro-ziwei-v3 or iztro-ziwei-v3-fast; for Qimen, use iztro-qimen-v3 or iztro-qimen-v3-fast. For Qimen, pass the user's local ISO 8601 question time as current_datetime when sending the message.

When reasoning_effort is omitted, iztro-ziwei-v3 and iztro-qimen-v3 enable thinking by default, while both fast models disable it. You can set reasoning_effort when creating a session and override it when sending, editing, or resending a message. Precedence is: explicit request setting, explicit session setting, selected model default.

{
  "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 Use cases and models for report and follow-up prompts.

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.