# Using The New Public API

To get started, sign up for a new account at <https://beta.capriai.us> and start a 2 week free trial! You'll need an account to get your Agent ID and Token. See the [quickstart-guides](https://help.capriai.us/quickstart-guides "mention") for information on setting up an agent (use the "Beta" section)!

### Authorization

You'll need a Capri API Token to authorize your API Calls. Grab it [here](https://beta.capriai.us/home/organization?show=tokens).

<figure><img src="https://3405410158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FceowT5YuHiPO9waGTyaH%2Fuploads%2FcHFIJCAjyQ7XRMWIB7v1%2Fimage.png?alt=media&#x26;token=148bf82b-04dc-42b2-bb49-acdb1feeea76" alt=""><figcaption></figcaption></figure>

### Base URL:

```
// https://api.capriai.us/v1/{endpoint}
```

### Conversations

```
https://api.capriai.us/v1/conversation/query
```

#### Request:

## Query your Capri Ai Agent

<mark style="color:green;">`POST`</mark> `https://api.capriai.us/v1/conversation/query`

Send a user query and receive the final response as well as all intermediate actions that your agent predicted during it's conversation turn.

#### Request Header

<table><thead><tr><th width="532">Name</th><th>Description</th></tr></thead><tbody><tr><td>Authorization<mark style="color:red;">*</mark></td><td><p>(required) The value should be </p><p>"Bearer {YourCapriToken}", with a space in between "bearer" and your token, and no brackets.</p><p></p><p>For example, "Bearer oxoxooxoxxo"</p></td></tr></tbody></table>

#### Request Body

| Name                                        | Type   | Description                                                                                                                          |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| agent<mark style="color:red;">\*</mark>     | String | (required) The desired agent ID, found at the very end of the URL of your agent's details page <https://beta.capriai.us/home/agents> |
| sessionId<mark style="color:red;">\*</mark> | String | (required)  Any random string, provided by the application calling the capri API. Minimum of 8 unique characters required.           |
| message<mark style="color:red;">\*</mark>   | String | (required)  The user's query to be responded to by the agent                                                                         |

{% tabs %}
{% tab title="200: OK Successful " %}
Response Parameters:

```
{
  "finalResponse" : //Your agent's final conversational response,
  "actions" : //array of actions your agent took during it's turn
       [
           {
              "eventId" : //unique Id representing the action
              "sender" : //who sent the message ('bot' or 'human'),
              "kind" : // the kind of action (i.e., googleSheet, ghlCalendar, etc),
              "accountId" : //id of which resource was used for this action,
              "accountName" : //name of which resource was used for this action,
              "deleted" : //boolean, represents if a user manually corrected the action from the emulator,
              "action" : //the action type (i.e., 'read', 'write', tag', etc),
              "eventData" : //event details (optional, only present if required such as calendar event dates and time ranges)
              "reference" : //reference url for the resource that was used (optional),
              "timestamp" : //time the action took place (epoch time in milliseconds)
           },
           {...}
        ]
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or API Token not found" %}

```
{
    "message": string,
    "error": 'Unauthorized'
    "statusCode": 401
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request body. Most commonly occurs when a required request parameter is missing or invalid" %}

```
{
    "message": string,
    "error": 'Bad Request'
    "statusCode": 400
}
```

{% endtab %}
{% endtabs %}

### Export GHL Conversation

```
https://api.capriai.us/v1/extension/leadconnector/conversations
```

#### Required Parameters

1. `url`: The target URL for sending data.
2. `capri_token`: A security token for authentication.

These parameters should be added as "custom data" parameters in GHL (GoHighLevel)

<figure><img src="https://3405410158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FceowT5YuHiPO9waGTyaH%2Fuploads%2FtfdcFCczxRcyxkAtgXUB%2Fimage.png?alt=media&#x26;token=e4079b1b-2f56-448e-8c96-5c47a2918406" alt=""><figcaption></figcaption></figure>

#### Response Structure

Upon successfully calling the export conversations API, you will receive a JSON response structured as follows:

```json
{
    "conversations": [
        {
            "conversationId": "string",
            "participants": [
                {
                    "participantId": "string",
                    "name": "string",
                    "role": "string"
                },
                ...
            ],
            "messages": [
                {
                    "messageId": "string",
                    "sender": "string",
                    "content": "string",
                    "timestamp": "epoch time in milliseconds"
                },
                ...
            ]
        },
        ...
    ],
    "pagination": {
        "currentPage": number,
        "totalPages": number,
        "pageSize": number,
        "totalItems": number
    }
}
```

#### Handling Errors

Ensure to handle potential errors when making the API call:

* **401: Unauthorized** - Check if the API token is correct and has the necessary permissions.
* **400: Bad Request** - Ensure all mandatory parameters are included and valid.

By managing both successes and errors effectively, you can seamlessly integrate conversation data into your workflow.