# 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](/quickstart-guides/getting-started-with-capri-ai.md) 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="/files/kvzhFqe4LPOrnzH5F0JP" 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="/files/C4oYRaP14VE4eskwsicn" 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.capriai.us/api-and-developer-tools/using-the-new-public-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.