---
title: Programmatic use of agent (API)
---

- Reports can be filled out with agent through the API&#x20;
- 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](http://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"
```

```json title="Queued"
{
  "state": "QUEUED",
  "stage": "queued",
  "completedSections": 0,
  "totalSections": 0
}
```

```json title="Running"
{
  "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": {}
      }
    },
    ...
  ]
}


```

```json title="Completed"
{
  "state": "COMPLETED",
  "stage": "completed",
  "completedSections": 3,
  "totalSections": 3,
  "handover": {
    "summary": "Report filled. Review the generated sections.",
    "actions": []
  }
}


```

```json title="Failed"
{
  "state": "FAILED",
  "stage": "failed",
  "completedSections": 3,
  "totalSections": 3,
  "error": "Report saving failed"
}
```
