Skip to main content

​
Coach API guide

This page documents Coach endpoints with practical usage guidance, parameter tables, and request/response examples.
For full contract detail and interactive testing, use the API Explorer in the sidebar.

​
Endpoint reference

​
GET /api/coach/bootstrap

Use this endpoint to load initial Coach state when the authenticated user opens the Coach surface. Query parameters
NameTypeRequiredDescription
None--No query parameters are required.
curl "<NSDK_API_BASE_URL>/api/coach/bootstrap" \
  -H "Authorization: Bearer <access-jwt>"
Common errors
  • 401: missing or expired access token
  • 429: rate-limit protection

​
POST /api/chat/session/create

Use this endpoint to create a new session before sending chat messages. Request body
NameTypeRequiredDescription
chatTypestringYesChat mode. Supported values include free, metric, opp.
userIdstringYesAuthenticated user identifier.
curl -X POST "<NSDK_API_BASE_URL>/api/chat/session/create" \
  -H "Authorization: Bearer <access-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "chatType": "free",
    "userId": "1005"
  }'
Common errors
  • 400: invalid payload fields
  • 401: access token invalid or missing
  • 429: rate-limit protection

​
GET /api/chat/sessions/list

Use this endpoint to fetch existing chat sessions for the current user. Query parameters
NameTypeRequiredDescription
None--No query parameters are required.
curl "<NSDK_API_BASE_URL>/api/chat/sessions/list" \
  -H "Authorization: Bearer <access-jwt>"
Common errors
  • 401: access token invalid or missing
  • 429: rate-limit protection

​
GET /api/chat/history/{session_id}

Use this endpoint to load the message history of one session. Path parameters
NameTypeRequiredDescription
session_idstringYesSession identifier returned by create/list endpoints.
curl "<NSDK_API_BASE_URL>/api/chat/history/123" \
  -H "Authorization: Bearer <access-jwt>"
Common errors
  • 401: access token invalid or missing
  • 404: session not found
  • 429: rate-limit protection

​
POST /api/chat/send

Use this endpoint to send one message and receive streamed assistant output via SSE. Request body
NameTypeRequiredDescription
sessionIdstringYesExisting chat session id.
userIdstringYesAuthenticated user identifier.
payloadTypestringYesMessage payload type, currently text.
payloadobjectYesPayload object, including text.
curl -N -X POST "<NSDK_API_BASE_URL>/api/chat/send" \
  -H "Authorization: Bearer <access-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "123",
    "userId": "1005",
    "payloadType": "text",
    "payload": { "text": "How can I reduce costs?" }
  }'
Common errors
  • 400: invalid message payload
  • 401: access token invalid or missing
  • 500: transient runtime error during orchestration/streaming

​
POST /api/chat/followup_questions

Use this endpoint to generate guided follow-up questions for an answer. Request body
NameTypeRequiredDescription
questionstringYesOriginal user question.
answerstringYesAssistant answer context.
countintegerYesNumber of follow-up suggestions to return.
curl -X POST "<NSDK_API_BASE_URL>/api/chat/followup_questions" \
  -H "Authorization: Bearer <access-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How can I reduce costs?",
    "answer": "Review recurring spend first.",
    "count": 3
  }'
Common errors
  • 400: invalid payload fields
  • 401: access token invalid or missing
  • 429: rate-limit protection

​
PUT /api/chat/session/{session_id}/binding

Use this endpoint to bind a chat session to a specific context entity (for example, an insight). Path parameters
NameTypeRequiredDescription
session_idstringYesSession identifier to bind.
Request body
NameTypeRequiredDescription
bindingTypestringYesContext type, for example insight.
bindingIdstringYesContext entity identifier.
curl -X PUT "<NSDK_API_BASE_URL>/api/chat/session/123/binding" \
  -H "Authorization: Bearer <access-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "bindingType": "insight",
    "bindingId": "12001"
  }'
Common errors
  • 400: invalid binding payload
  • 401: access token invalid or missing
  • 429: rate-limit protection

​
POST /api/chat/session/{session_id}/message-feedback

Use this endpoint to capture explicit user feedback for an assistant message. Path parameters
NameTypeRequiredDescription
session_idstringYesSession identifier.
Request body
NameTypeRequiredDescription
messageIdstringYesAssistant message identifier.
feedbackstringYesFeedback value, typically positive or negative.
curl -X POST "<NSDK_API_BASE_URL>/api/chat/session/123/message-feedback" \
  -H "Authorization: Bearer <access-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "m_101",
    "feedback": "positive"
  }'
Common errors
  • 400: invalid feedback payload
  • 401: access token invalid or missing
  • 404: session or message not found