Programmatic use of agent (API)
- Reports can be filled out with agent through the API
- The report object needs to be configured with a direct link, typically used to open a report in Convier from CRM
- The service principal requesting the report filling needs to be given access to the Convier enterprise application with role Task.Read
- Generate access token with OIDC provider for the Convier application
- Then:
Exchange OIDC access token for session cookie
curl -X POST 'https://$host/convier/token/exchange' \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"sessionId": "$CONVIER_SESSION_ID",
"expiresAt": "2026-11-18T11:00:00Z"
}Retrieve introduction to report or object
Endpoint to gather introductory data. System instruction for how to generate introduction based on loaded data is determined in the active agent configuration.
curl -X GET \
'https://$host/convier/api/agent/$projectId/introduction/$direct_link_key/$direct_link_value' \
--cookie "CONVIER_SESSION_ID=$SESSION_ID"
{
"introduction": "The customer and connected entities warrant further review.",
"keywords": ["customer", "risk", "review"]
}Start report processing
The /save part of the URL is optional and indicates wether or not the report should be saved to report storage after completion. Saving will make it possible for users to continue on the filled report. $direct_link_key is defined in Convier configuration, and $direct_link_value is typically a case number
curl -X POST \
'https://$host/api/agent/$project_id/reports/process/$direct_link_key/$direct_link_value' \
--cookie "CONVIER_SESSION_ID=$CONVIER_SESSION_ID" \
-H 'Content-Type: application/json' \
-d '{}'
{
"requestId": "$requestId"
}Poll processing state
curl \
'https://$host/api/agent/$project_id/reports/process/$requestId' \
--cookie "CONVIER_SESSION_ID=$CONVIER_SESSION_ID"{
"state": "QUEUED",
"stage": "queued",
"completedSections": 0,
"totalSections": 0
}{
"state": "RUNNING",
"stage": "preparing_section",
"currentSectionId": "summary",
"completedSections": 1,
"totalSections": 3
"sections": [
{
"sectionId": "section-1",
"startedAt": "2026-11-18T10:00:00Z",
"completedAt": "2026-11-18T10:00:10Z",
"result": {
"state": "COMPLETED",
"stage": "completed",
"content": {
"type": "doc",
"content": []
},
"context": {}
}
},
...
]
}
{
"state": "COMPLETED",
"stage": "completed",
"completedSections": 3,
"totalSections": 3,
"handover": {
"summary": "Report filled. Review the generated sections.",
"actions": []
}
}
{
"state": "FAILED",
"stage": "failed",
"completedSections": 3,
"totalSections": 3,
"error": "Report saving failed"
}Last updated on