Normally you send the whole conversation on every request. A session moves that history to the server: you send the new message, we prepend the rest.
When to use one#
| Approach | Use it when |
|---|---|
| Send the full history yourself | You already store the conversation, or you need exact control over what the model sees. This is the default and it is stateless. |
| A server session | You want a conversation to persist across processes, devices or restarts without building storage for it. |
Sessions are opt-in
Nothing is stored unless you ask. A plain request writes a billing record and no messages.Starting one#
# Opt in once, and keep the id you get back.first = client.chat.completions.create(model="upfyn-yuva",messages=[{"role": "user", "content": "My name is Anit."}],extra_body={"persist_session": True},)session_id = first.session_id # e.g. "sess_7c19..."
persist_session must be exactly true. The response carries session_id; keep it.
Continuing it
# Later turns send ONLY the new message. The server has the rest.second = client.chat.completions.create(model="upfyn-yuva",messages=[{"role": "user", "content": "What's my name?"}],extra_body={"session_id": session_id},)print(second.choices[0].message.content) # "Your name is Anit."
Do not resend the history
When you passsession_id, the server loads the prior turns and prepends them. Sending them yourself as well duplicates every message — you pay for the tokens twice and the model sees the conversation stutter.chat_ref is not session_id#
chat_ref is an opaque id of your own — up to 128 characters — used to group requests for per-conversation allowances and reporting. It does not make the server load history.
- You keep the transcript, but want per-chat accounting →
chat_ref. - You want us to keep the transcript →
session_id+persist_session.
Managing sessions#
curl "https://ai.upfyn.com/v1/me/sessions?limit=20" \-H "Authorization: Bearer $UPFYN_API_KEY"
| Call | Does |
|---|---|
GET /v1/me/sessions | Lists sessions, newest first. Up to 200. |
GET /v1/me/sessions/{id} | One session with its messages. |
PATCH /v1/me/sessions/{id} | Rename, or set status to archived. |
DELETE /v1/me/sessions/{id} | Removes the session and its messages. |
Writes need the full scope
Creating, renaming and deleting sessions requiregateway:full. Reading them needs usage:read. A narrow inference key can use a session but cannot manage one.What a session stores#
- The messages in the conversation, including any system prompt you sent and any tool calls.
- The model, a title, a message count and the credits it has used.
This is the same data your Logs page reads for its Sessions, Tool calls and System prompts tabs — which is exactly why a request made without a session appears under Generations but nowhere else. Deleting a session deletes its messages; the billing record stays, because your invoice has to keep adding up.
What we retain and for how long is set out in the Privacy Policy, and the controls are on Preferences.