Assist API

POST /api/v1/assist puts your organization’s AI assistant behind one endpoint: your chatbot, internal portal or CLI sends a question; the assistant answers grounded in your published knowledge base, exactly as it would in ServiceOps itself.

Required scope: ai_assist.use — see API keys.

Request

curl https://YOUR_SERVICEOPS_DOMAIN/api/v1/assist \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How do I reset my VPN access?",
    "conversationId": null,
    "endUserRef": "employee-4512"
  }'

Field	Required	Meaning
message	yes	The question, in natural language
conversationId	no	Continue an earlier conversation; omit to start a new one
endUserRef	no	Your own opaque reference for the end user asking — lets conversations group per user without sending personal data

Response

{
  "conversationId": "b7b2…",
  "message": "To reset your VPN access, open… ",
  "status": "success",
  "contextSource": "KNOWLEDGE_BASE"
}

Field	Meaning
conversationId	Send it back on the next turn to keep context
message	The assistant’s answer
contextSource	What grounded the answer — a knowledge-backed reply is distinguishable from a model-only one, so your integration can treat them differently

Conversation continuity

Pass the returned conversationId on the next call and the assistant keeps the thread — follow-up questions understand what came before. A conversation belongs to your organization: an id from elsewhere is refused and a fresh conversation opens instead.

Good citizenship

• One conversation per end user (via endUserRef) gives the best answers and clean usage accounting.
• Show contextSource to your users when you can — “based on our knowledge base” builds exactly the right amount of trust.
• Calls appear in the usage ledger and count toward AI quotas.