Conversation context

What happens on each call

1. You send context_id plus the new message or messages.
2. We load the earlier turns of that thread, oldest first, and put them in front of your messages.
3. The combined conversation is trimmed to fit the token budget.
4. The result is sent to a provider, with the usual automatic failover.
5. Your message and the reply are stored against the thread, so the next call can replay them.

Only successful turns are stored for replay. If a call fails, it leaves nothing behind, so retrying does not make it look like you asked twice.

Reference

Ids look like ctx- followed by a random string. Treat one as a secret: it names a conversation. Store it wherever you keep the rest of your session state.

Inspect a thread

GET /api/v1/contexts/{context_id}

Shows exactly what we would replay, and how big it is. Useful when a thread stops behaving the way you expect.

curl https://dreamprompting.com/api/v1/contexts/ctx-Ngz5JE-UdyE_YB6WfVz7hQ \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "context_id": "ctx-Ngz5JE-UdyE_YB6WfVz7hQ",
  "messages": [
    {"role": "user", "content": "My project is called Kuza."},
    {"role": "assistant", "content": "Noted."}
  ],
  "turns": 2,
  "estimated_tokens": 12,
  "token_budget": 12000,
  "trimmed_turns": 0
}

trimmed_turns counts older turns the budget is currently leaving out. An unknown id returns an empty thread rather than an error, because a thread only exists once its first turn has been answered.

Streaming

Context works with "stream": true. The body carries standard OpenAI chunks with no room for extra fields, so read the id from the X-Context-Id response header.

import requests

r = requests.post(
    "https://dreamprompting.com/api/v1/chat/completions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"model": "auto", "context_id": "new", "stream": True,
          "messages": [{"role": "user", "content": "Hello"}]},
    stream=True,
)
context_id = r.headers["X-Context-Id"]   # keep this for the next turn

for line in r.iter_lines():
    if line:
        print(line.decode())

Trimming, and why threads do not grow forever

A conversation that keeps growing eventually exceeds what any provider will accept, at which point every call fails. To avoid that, a replayed thread is trimmed to about 12,000 tokens:

• System messages always survive. They carry the instructions that define behaviour, so losing them changes the assistant mid-conversation.
• Newest turns win. Older turns are dropped first, because recent context usually matters more.
• Nothing is deleted. Trimming decides what gets replayed; the full thread stays in your usage history.

If your thread needs to remember something permanently, put it in a system message rather than relying on an early user turn, since a system message is never trimmed away.

Privacy and scoping

• A thread belongs to the account that created it. Another account cannot read it, even with the id.
• Any active key on your own account can use your threads, so rotating a key does not lose them.
• Threads are stored on our side, in the same request log that powers your usage page. Do not put secrets in a conversation you would not want stored.
• Ids are unguessable, but treat one as a credential for that conversation and keep it server side.

When to use it, and when not to

One thread is one conversation. If your app serves several people, create a thread per person and store the id next to that person's session. Do not share one thread across users, or their conversations will run together.

Errors