What the Conversation AI API Does
The Conversation AI API exposes core Conversation AI capabilities through API access.
You can use the API to:
Create agents.
Search agents.
Update agents.
Delete agents.
Attach actions to agents.
Update actions.
Retrieve generation details.
The API is useful when your team needs a consistent setup across many accounts or wants to report on AI-generated responses outside Kyrios.
Create a Private Integration
Go to Settings > Private Integrations.
Click Create new integration to start creating an API v2.0 private integration.
Select Conversation AI Scopes
In the Scopes step, select the Conversation AI scopes that your integration needs.
Use the minimum scope required for the integration. Common scopes include:
conversationaireadonly
conversationaiwrite
Read-only scope is best for reporting and audits. A write scope is required when the integration needs to create or update Conversation AI resources.
Copy and Maintain the Access Token
After creating the private integration, copy the access token. Use this token to authenticate API calls. Rotate tokens regularly for security. Kyrios recommends rotating access tokens every 90 days. You can rotate a token immediately or rotate it later with a grace period so connected apps can be updated.
Authentication Options
Conversation AI API access can use either:
Private Integration Token for server-to-server integrations.
JWT authentication for OAuth-based app flows.
Use a Private Integration Token when your team controls the server or script making the API calls. Use JWT when building an OAuth-based app experience.
Conversation AI API Resources
The Conversation AI API includes endpoints for agents, actions, and generations.
Agents
Agent endpoints are used to create, find, update, retrieve, and delete Conversation AI agents.
Common agent actions include:
Create an agent
Search agents
Update an agent
Get an agent
Delete an agent
Actions
Action endpoints are used to manage actions attached to a Conversation AI agent.
Common actions include:
Attach action to agent
List actions for an agent
Get action by ID
Update action
Remove action from agent
Update follow-up settings
Generations
Generation endpoints are used to retrieve AI response details.
Use generation data for:
QA review
Reporting
Compliance exports
Conversation audits
Analytics dashboards
Common Issues and Fixes
API request returns 403
A 403 usually means the token does not have the required scope or is not valid for the target account. Check that the private integration includes the correct Conversation AI scope.
Agent updates are not working
Confirm the token includes write access. Read-only scopes can retrieve data but cannot create or update Conversation AI resources.
The integration cannot find an agent
Use the Agents API to create or search agents first. Use the returned agent ID for later API requests.
The token may be compromised
Rotate and expire the token immediately. Update the connected app with the new token before making more API calls.
FAQ
Do I need an account token for Conversation AI API calls?
Yes. Use an account-level private integration token so API calls run in the correct account context.
Can I use both Private Integration Tokens and JWT?
Yes. Use Private Integration Tokens for simple server-to-server integrations. Use JWT for OAuth-based app flows.
Where do I find the agent ID?
Create or search agents through the Agents API. Use the returned agent ID in later requests.
How do I audit AI responses programmatically?
Use the Generations endpoint to retrieve message-level AI response details.
What causes a 403 error when my token looks valid?
The token may be missing the required scope, or the token may not belong to the target account.