Sessions
List sessions, filter by companion or client, and retrieve conversation transcripts
Every connection creates a session. A session captures the full configuration — which companion, tools, knowledge, and FAQs were attached — along with timing data and the complete conversation transcript between the user and the agent.
The Sessions API gives you two endpoints:
| Endpoint | What you get |
|---|---|
GET /public/sessions | A paginated list of sessions with filters for companion, client, tags, and free-text search |
GET /public/sessions/{sessionId} | Full session details including configuration, timing, and the complete conversation transcript |
Getting the session ID
When you create a connection, the response includes a connection.id. This is the session ID you use to query session data later.
curl -X POST https://companion-api.napster.com/public/connections \
-H "X-Api-Key: $NAPSTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"companionId": "comp_abc123",
"providerConfig": {
"voiceId": "alloy",
"settings": {}
}
}'Response:
{
"token": "eyJhbGci...",
"connection": {
"id": "sess_abc123"
}
}Store the connection.id on your backend. You need it to retrieve session details and transcripts.
Listing sessions
Retrieve a paginated list of sessions across your project:
curl https://companion-api.napster.com/public/sessions?pageSize=10 \
-H "X-Api-Key: $NAPSTER_API_KEY"Response:
{
"items": [
{
"id": "sess_abc123",
"companionId": "comp_abc123",
"functions": ["fn_def456"],
"knowledgeBaseId": "kb_abc123",
"faqIds": ["faq_abc123"],
"externalClientId": "user_12345",
"tags": {
"environment": "production",
"channel": "web"
},
"createdAt": 1710000000,
"startedAt": 1710000005,
"closedAt": 1710000300
}
],
"filteredCount": 1,
"totalCount": 42,
"pageIndex": 0,
"pageSize": 10
}Filtering
Use query parameters to narrow results:
| Parameter | Type | Description |
|---|---|---|
companionId | string | Filter by companion |
externalClientId | string | Filter by your external user or client identifier |
search | string | Free-text search across sessions |
tags | string | Filter by tag key-value pairs |
pageIndex | integer | Page number (zero-based) |
pageSize | integer | Number of results per page |
curl "https://companion-api.napster.com/public/sessions?companionId=comp_abc123&pageSize=20" \
-H "X-Api-Key: $NAPSTER_API_KEY"Retrieving a session
Get the full details of a session, including the conversation transcript:
curl https://companion-api.napster.com/public/sessions/sess_abc123 \
-H "X-Api-Key: $NAPSTER_API_KEY"Response:
{
"id": "sess_abc123",
"companionId": "comp_abc123",
"functions": ["fn_def456"],
"knowledgeBaseId": "kb_abc123",
"faqIds": ["faq_abc123"],
"externalClientId": "user_12345",
"tags": {
"environment": "production"
},
"createdAt": 1710000000,
"startedAt": 1710000005,
"closedAt": 1710000300,
"conversation": {
"items": [
{
"role": "agent",
"text": "Hi there! How can I help you today?",
"timestamp": 1710000006
},
{
"role": "user",
"text": "I'd like to check the status of my order.",
"timestamp": 1710000010
},
{
"role": "agent",
"text": "Let me look that up for you. Your order #ORD-7890 shipped yesterday and is expected to arrive by Friday.",
"timestamp": 1710000015
}
]
}
}The conversation.items array contains each message in chronological order. Each item includes:
| Field | Description |
|---|---|
role | Who sent the message (agent or user) |
text | The message content |
timestamp | Unix timestamp of the message |