Sessions
Create, list, update, and end desktop sessions through the Talkturo API — manage real-time coaching sessions for the Close AI desktop app.
curl --request GET \
--url "https://app.talkturo.com/api/sessions" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt" \
--header "X-Talkturo-Account: acc_northstar_sales"
const response = await fetch("https://app.talkturo.com/api/sessions", {
method: "GET",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt",
"X-Talkturo-Account": "acc_northstar_sales",
},
});
const data = await response.json();
console.log(data);
{
"sessions": [
{
"id": "f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6",
"user_id": "7f4f95a3-9f14-4f59-a9d4-e7b9250996de",
"uid": "sess_8h1r2m4q",
"account_id": "c2f8de7d-1f57-4388-b4f1-3102a5d34518",
"title": "Discovery call with Greenline Solar",
"session_type": "listen",
"started_at": "2026-02-18T15:04:11.000Z",
"ended_at": "2026-02-18T15:42:39.000Z",
"status": "completed",
"duration_seconds": 2308,
"updated_at": "2026-02-18T15:43:05.000Z"
},
{
"id": "3be8aaea-a2c8-466f-9984-b8780b3d6a50",
"user_id": "7f4f95a3-9f14-4f59-a9d4-e7b9250996de",
"uid": "sess_j7k2p9vn",
"account_id": "c2f8de7d-1f57-4388-b4f1-3102a5d34518",
"title": null,
"session_type": "ask",
"started_at": "2026-02-18T16:10:02.000Z",
"ended_at": null,
"status": "active",
"duration_seconds": null,
"updated_at": "2026-02-18T16:10:02.000Z"
}
]
}
{
"error": "Unauthorized"
}
curl --request POST \
--url "https://app.talkturo.com/api/sessions" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt" \
--header "X-Talkturo-Account: acc_northstar_sales" \
--header "Content-Type: application/json" \
--data '{
"mode": "create",
"session_type": "listen"
}'
const response = await fetch("https://app.talkturo.com/api/sessions", {
method: "POST",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt",
"X-Talkturo-Account": "acc_northstar_sales",
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "create",
session_type: "listen",
}),
});
const data = await response.json();
console.log(data);
{
"id": "3be8aaea-a2c8-466f-9984-b8780b3d6a50"
}
{
"error": "Invalid session_type"
}
curl --request GET \
--url "https://app.talkturo.com/api/sessions/f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt"
const response = await fetch(
"https://app.talkturo.com/api/sessions/f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6",
{
method: "GET",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt",
},
}
);
const data = await response.json();
console.log(data);
{
"session": {
"id": "f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6",
"user_id": "7f4f95a3-9f14-4f59-a9d4-e7b9250996de",
"uid": "sess_8h1r2m4q",
"account_id": "c2f8de7d-1f57-4388-b4f1-3102a5d34518",
"title": "Discovery call with Greenline Solar",
"session_type": "listen",
"status": "completed",
"notes": "Strong discovery questions. Missed budget confirmation.",
"voice_metrics": {
"talk_share_pct": 46,
"wpm": 132,
"patience_pct": 82,
"longest_monologue_seconds": 38
},
"started_at": "2026-02-18T15:04:11.000Z",
"ended_at": "2026-02-18T15:42:39.000Z",
"duration_seconds": 2308,
"updated_at": "2026-02-18T15:43:05.000Z",
"created_at": "2026-02-18T15:04:11.000Z"
}
}
{
"error": "Session not found"
}
curl --request PATCH \
--url "https://app.talkturo.com/api/sessions/f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt" \
--header "Content-Type: application/json" \
--data '{
"title": "Discovery call with Greenline Solar",
"status": "completed",
"notes": "Strong discovery questions. Missed budget confirmation.",
"voice_metrics": {
"talk_share_pct": 46,
"wpm": 132,
"patience_pct": 82,
"longest_monologue_seconds": 38
},
"end": true
}'
const response = await fetch(
"https://app.talkturo.com/api/sessions/f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6",
{
method: "PATCH",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt",
"Content-Type": "application/json",
},
body: JSON.stringify({
title: "Discovery call with Greenline Solar",
status: "completed",
notes: "Strong discovery questions. Missed budget confirmation.",
voice_metrics: {
talk_share_pct: 46,
wpm: 132,
patience_pct: 82,
longest_monologue_seconds: 38,
},
end: true,
}),
}
);
const data = await response.json();
console.log(data);
{
"changes": 1
}
{
"error": "Invalid status"
}
{
"error": "Session not found"
}
curl --request DELETE \
--url "https://app.talkturo.com/api/sessions/f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt"
const response = await fetch(
"https://app.talkturo.com/api/sessions/f9c5808d-e1da-4f1f-b1f0-d0b2f9923fc6",
{
method: "DELETE",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt",
},
}
);
const data = await response.json();
console.log(data);
{
"deleted": true
}
curl --request POST \
--url "https://app.talkturo.com/api/sessions/end-all" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt"
const response = await fetch("https://app.talkturo.com/api/sessions/end-all", {
method: "POST",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktopjwt",
},
});
const data = await response.json();
console.log(data);
{
"changes": 2
}
Endpoint summary
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /api/sessions | List desktop sessions | Desktop JWT |
POST | /api/sessions | Create a session | Desktop JWT |
GET | /api/sessions/{id} | Get a session by ID | Desktop JWT |
PATCH | /api/sessions/{id} | Update or end a session | Desktop JWT |
DELETE | /api/sessions/{id} | Delete a session | Desktop JWT |
POST | /api/sessions/end-all | End all active sessions | Desktop JWT |
Authenticate every request with a desktop JWT in the Authorization header. To scope requests to a specific workspace, add the optional X-Talkturo-Account header.
List sessions
Return the desktop sessions available to the authenticated user.
Headers
Bearer token containing a desktop JWT.
Workspace scope for the request. Omit this header to use the default workspace available to the authenticated desktop user.
Response fields
Array of session objects visible to the authenticated user.
Unique session UUID.
UUID of the user who owns the session.
Client-facing session identifier used by the desktop app.
Workspace UUID associated with the session.
Optional session title.
Session mode. Values are ask and listen.
Session start time in ISO 8601 format.
Session end time in ISO 8601 format, or null while the session is still active.
Current session status. Values are active and completed.
Computed session duration in seconds. Returns null until the session ends.
Last update time in ISO 8601 format.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid desktop JWT |
500 | Server error |
Create session
Create a new desktop session, or return the existing active session when you use getOrCreateActive.
Headers
Bearer token containing a desktop JWT.
Workspace scope for the new session.
Body parameters
Session creation mode. Defaults to create. Use getOrCreateActive to reuse an existing active session instead of creating a new one.
creategetOrCreateActiveResponse fields
UUID of the created session, or the active session returned by getOrCreateActive.
Errors
| Status | Meaning |
|---|---|
400 | Invalid request body |
401 | Missing or invalid desktop JWT |
500 | Server error |
Get session
Return a single session by ID.
Path parameters
Session UUID.
Headers
Bearer token containing a desktop JWT.
Response fields
Session record for the requested ID.
Unique session UUID.
UUID of the user who owns the session.
Client-facing session identifier used by the desktop app.
Workspace UUID associated with the session.
Optional session title.
Session mode. Values are ask and listen.
Current session status. Values are active and completed.
Optional session notes saved on the record.
Aggregated voice coaching metrics for the session, if available.
Percentage of session talk time attributed to the user.
Estimated speaking rate in words per minute.
Patience score expressed as a percentage.
Longest uninterrupted speaking segment in seconds.
Session start time in ISO 8601 format.
Session end time in ISO 8601 format, or null if the session is active.
Computed session duration in seconds.
Last update time in ISO 8601 format.
Creation time in ISO 8601 format.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid desktop JWT |
404 | Session not found |
500 | Server error |
Update session
Update mutable fields on a session. Set end to true to complete the session, stamp ended_at, compute duration_seconds, and trigger background AI analysis.
Ending a session is a state change, not a soft preview. When you send end: true, the API marks the session as completed and starts post-session analysis in the background.
Path parameters
Session UUID.
Headers
Bearer token containing a desktop JWT.
Body parameters
Session title.
Free-form notes attached to the session.
Voice coaching metrics to store on the session.
Estimated speaking rate in words per minute. Nested under voice_metrics.
Patience score expressed as a percentage. Nested under voice_metrics.
Longest uninterrupted speaking segment in seconds. Nested under voice_metrics.
When true, ends the session, sets ended_at, changes status to completed, computes duration_seconds, and triggers background AI analysis.
Response fields
Number of rows updated.
Errors
| Status | Meaning |
|---|---|
400 | Invalid request body |
401 | Missing or invalid desktop JWT |
404 | Session not found |
500 | Server error |
Delete session
Delete a session by ID.
Path parameters
Session UUID.
Headers
Bearer token containing a desktop JWT.
Response fields
Returns true when the session was deleted.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid desktop JWT |
500 | Server error |
End all active sessions
Complete every active session available to the authenticated desktop user.
This endpoint ends all active sessions in scope for the authenticated user. Review your workspace scoping before calling it from automation or shutdown handlers.
Headers
Bearer token containing a desktop JWT.
Response fields
Number of active sessions that were ended.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid desktop JWT |
500 | Server error |