> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a2v2.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Integrate A2V2.ai with your own systems — sync contacts, submit forms, extract document data, and embed the chat widget.

A2V2.ai gives you two ways to integrate the platform with your own product:
the **Open API** (a REST API for moving CRM data in and out programmatically)
and the **Widget JS API** (the embeddable chat widget you load on your site).
This section is written for developers. If you just want to add the agent to a
website without code, start with [Embed & Install](/embed/install) instead.

## Who this is for

<CardGroup cols={2}>
  <Card title="Backend / integration developers" icon="server">
    Use the **Open API** to create and update CRM contacts, submit forms, manage
    contact files, and run AI document extraction from your own backend.
  </Card>

  <Card title="Front-end / web developers" icon="code">
    Use the **Widget JS API** to embed the chat bubble and control it
    programmatically with `A2V2Widget.init()` / `.destroy()`.
  </Card>
</CardGroup>

## The two surfaces

| Surface             | Auth                      | What it's for                                                         | Reference                           |
| ------------------- | ------------------------- | --------------------------------------------------------------------- | ----------------------------------- |
| **Open API** (REST) | API key + secret (header) | Server-to-server: contacts, forms, contact files, document extraction | [Endpoints](/api/endpoints)         |
| **Widget JS API**   | None (public, per agent)  | Embed and control the chat widget in the browser                      | [Widget JS API](/api/widget-js-api) |

## Base URL

All Open API endpoints live under the `/v1/open` path on the A2V2.ai API host:

```text theme={null}
https://api.a2v2.ai/v1/open
```

<Note>
  `https://api.a2v2.ai` is the production API host. Every example in this section uses it
  as the base URL, followed by the fixed `/v1/open` path.
</Note>

The Widget JS API is served from a separate, public host and does not use the
`/v1/open` path:

```text theme={null}
https://chat-widget.a2v2.ai/embed.js
```

## Authentication at a glance

Open API requests authenticate with an **API key and secret** sent as request
headers. You create keys in the dashboard under **Settings → API Permissions**,
and each key is scoped to a single agent with explicit permissions.

```http theme={null}
X-API-Key: your-api-key
X-API-Secret: your-api-secret
Content-Type: application/json
```

Full details — including how keys are scoped and how to rotate them — are on the
[Authentication](/api/authentication) page.

## Response format

Every Open API response is JSON with a `success` flag.

<Tabs>
  <Tab title="Success">
    ```json theme={null}
    {
      "success": true,
      "message": "Operation completed successfully",
      "data": { }
    }
    ```
  </Tab>

  <Tab title="Error">
    ```json theme={null}
    {
      "success": false,
      "message": "Error description",
      "code": "ERROR_CODE",
      "validationErrors": [
        {
          "field": "primaryEmail",
          "message": "primaryEmail is mandatory for API contact creation",
          "value": null,
          "type": "any.required"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

List endpoints return a `pagination` object alongside `data`:

```json theme={null}
{
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 100,
    "itemsPerPage": 20,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}
```

## Rate limits

Each API key has its own rate limits, set when you create the key. The defaults
are **60 requests per minute** and **1,000 requests per hour**, and you can raise
them when configuring the key (up to 1,000/minute and 10,000/hour). Requests over
the limit return an error response — back off and retry.

## Health check

A lightweight, unauthenticated endpoint confirms the API is reachable:

```bash theme={null}
curl https://api.a2v2.ai/v1/open/health
```

```json theme={null}
{ "success": true, "message": "A2V2 Open API is healthy", "version": "1.0.0" }
```

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Create an API key and scope its permissions.
  </Card>

  <Card title="Endpoints" icon="list" href="/api/endpoints">
    Every Open API endpoint, grouped by domain.
  </Card>

  <Card title="Widget JS API" icon="comments" href="/api/widget-js-api">
    Embed and control the chat widget in the browser.
  </Card>

  <Card title="Embed & Install" icon="rocket" href="/embed/install">
    The no-code way to add your agent to a site.
  </Card>
</CardGroup>