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

# Introduction to CriaChat APIs

> Authentication, base URLs, and how to use CriaChat APIs to build integrations and chat experiences.

# Introduction to CriaChat APIs

Welcome to the CriaChat API Reference. This section explains how the APIs are organized, how authentication works, and how to make your first requests.

CriaChat provides public API categories designed for different integration needs:

* **Application APIs** — workspace automation and agent-facing integrations.
* **Client APIs** — custom chat interfaces and end-user messaging experiences.
* **Other APIs** — feature-specific endpoints used in certain flows (documented in their sections).

***

## Base URL

All API requests use:

`https://app.cria.chat/`

***

## Authentication

### Application APIs

Application APIs authenticate via a request header:

* `api_access_token: <YOUR_API_ACCESS_TOKEN>`

Keep this token server-side. Treat it as a secret.

### Client APIs

Client APIs are designed for end-user chat surfaces and typically use identifiers instead of an API token:

* `inbox_identifier`
* `contact_identifier`

`contact_identifier` is the **source id** returned when creating a contact (`source_id`).

Some Client API payloads also support an `identifier_hash` field for HMAC-style verification, depending on your use case.

***

## API namespaces (by path)

CriaChat separates intent by URL prefix:

* **Application APIs**: `/api/v1/...`
* **Client APIs**: `/public/api/v1/...`
* **Other APIs**: documented in their respective sections

***

## Quickstart (Application API)

### Verify your token

```bash theme={null}
curl -X GET "https://app.cria.chat/api/v1/profile" \
  -H "api_access_token: YOUR_API_ACCESS_TOKEN"
```

***

## Quickstart (Client API)

This is the common “happy path” for embedded chat experiences: **create contact → create conversation → send message**.

### 1) Create (or update) a contact

```bash theme={null}
curl -X POST "https://app.cria.chat/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "external-user-123",
    "name": "Alice",
    "email": "alice@acme.inc",
    "phone_number": "+5511999999999",
    "custom_attributes": {}
  }'
```

From the response, store:

* `source_id` → this is your `contact_identifier`

### 2) Create a conversation

```bash theme={null}
curl -X POST "https://app.cria.chat/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/CONTACT_IDENTIFIER/conversations" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_attributes": {}
  }'
```

From the response, store:

* `id` → this is your `conversation_id`

### 3) Send a message

```bash theme={null}
curl -X POST "https://app.cria.chat/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/CONTACT_IDENTIFIER/conversations/CONVERSATION_ID/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello! I need help with my order."
  }'
```

***

## Conventions and reliability notes

* Use the correct namespace: `/api/v1` (Application) vs `/public/api/v1` (Client)
* Treat webhook/event deliveries (when enabled) as “may repeat” signals and implement idempotency in your automation layer
* Log key identifiers for debugging: `inbox_identifier`, `contact_identifier`, `conversation_id`, `message_id`

***

## Troubleshooting

When behavior differs from expectations:

* Confirm the base URL and path prefix (`/api/v1` vs `/public/api/v1`)
* Confirm whether the endpoint expects `api_access_token` or identifiers
* Inspect real requests made by the CriaChat UI (browser DevTools → Network) and replicate the same payload structure