Sessions

Add a session_id to any /chat request and NinjaChat stores the conversation server-side for 7 days. No message arrays to manage, no growing payloads.

First request

{
  "model": "gpt-5",
  "messages": [{"role": "user", "content": "My name is Alice. I work in fintech."}],
  "session_id": "user-alice-1"
}

Second request — history injected automatically

{
  "model": "gpt-5",
  "messages": [{"role": "user", "content": "What do you know about me?"}],
  "session_id": "user-alice-1"
}

“You told me your name is Alice and you work in fintech.”

Responses include where the conversation stands:

{
  "choices": [{"message": {"role": "assistant", "content": "You told me..."}}],
  "session": {"id": "user-alice-1", "message_count": 4},
  "cost": {"this_request": "$0.0012"}
}

Sessions are created on first use — you can just start chatting with a new session_id. IDs are 1–64 chars of [a-zA-Z0-9_-], scoped to your API key.

Manage sessions

Endpoint	Does
`POST /api/v1/sessions`	Create explicitly (omit `session_id` for an auto-generated one)
`GET /api/v1/sessions/{id}`	Stored messages + timestamps. Once a session has auto-summarized (see below), this is the summary message plus the most recent messages — not the original full transcript.
`GET /api/v1/sessions/{id}/export?format=markdown`	Export as Markdown (or `json`)
`DELETE /api/v1/sessions/{id}`	Delete

A support bot in 15 lines

import requests, os

BASE = "https://www.ninjachat.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['NINJACHAT_API_KEY']}"}

def chat(session_id: str, message: str) -> str:
    r = requests.post(f"{BASE}/chat", headers=HEADERS, json={
        "model": "gpt-5",
        "messages": [{"role": "user", "content": message}],
        "session_id": session_id,
    })
    return r.json()["choices"][0]["message"]["content"]

session = "support-alice-123"
print(chat(session, "Hi, my order #4521 hasn't arrived yet."))
print(chat(session, "I ordered it 2 weeks ago."))     # remembers the order number
print(chat(session, "What's the refund policy?"))     # remembers everything

Limits

Property	Value
TTL	7 days from last activity
Ownership	Tied to your API key; other keys can’t read them
Caching	Auto-disabled with sessions (history changes every turn)

Message limits

Sessions don’t grow forever, but they don’t just drop old turns either. Once a session passes 60 stored messages, it auto-summarizes in the background: an AI model (infrastructure-only, not billed to you) compresses everything except the most recent 20 messages into a single structured summary message (established facts, character/persona state, open threads, tone preferences), which then replaces those older turns. The session keeps going from summary + last 20 rather than growing unbounded. There’s also a hard emergency ceiling — if a session somehow reaches 100 messages before a pending summarization finishes, it’s truncated to the most recent 50 so a single session can never grow without bound. In normal use, summarization at 60 messages means you’ll rarely see this ceiling.

Get Started

Chat

Superpowers

Media & Search

Reference

Manage sessions

A support bot in 15 lines

Limits

Message limits

​Manage sessions

​A support bot in 15 lines

​Limits

​Message limits

Manage sessions

A support bot in 15 lines

Limits

Message limits