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

# M2M API Overview

> How to structure an Uppzy M2M integration across authentication, documents, chat, sessions, and analytics.

Uppzy M2M API is designed for server-to-server integrations. A typical integration:

1. Authenticates with an API key
2. Targets a specific tenant and site
3. Uploads or manages reference content
4. Sends chat requests
5. Tracks quality with feedback, sessions, and statistics

## Base URL

```text theme={null}
https://api.uppzy.com/api/v1
```

## Authentication model

All M2M requests require an API key in the request headers.

```http theme={null}
X-API-Key: <YOUR_API_KEY>
```

Read [API Authentication](/developer/api-authentication) before implementing your client.

## Main resource model

Most M2M integrations work with three identifiers:

* `tenant_id`: the workspace-level scope
* `site_id`: the website or chatbot scope
* `session_id`: the conversation scope

In practice:

* Tenant endpoints are useful for limits and account-level checks
* Site endpoints are used for documents, chat, sessions, and statistics
* Session IDs help you keep conversation continuity for a user or channel

## Endpoint families

### Tenant endpoints

Use tenant endpoints for environment checks and account-level information.

Common use cases:

* Verify limits before traffic starts
* Check usage at workspace level
* Confirm tenant-level statistics

Reference:

* [Create API Key](/api-reference/endpoint/tenant-api-key-create)

### Document endpoints

Use document endpoints to load the content the assistant should rely on.

Supported flows include:

* Upload file document
* Create text document
* Create Q\&A document

Reference:

* [M2M Upload File Document](/api-reference/endpoint/m2m-documents-upload)
* [M2M Create Text Document](/api-reference/endpoint/m2m-documents-text)
* [M2M Create Q\&A Document](/api-reference/endpoint/m2m-documents-qa)

### Chat endpoints

Use chat endpoints to send messages to the assistant.

Two main patterns:

* Sync chat: request and answer in one round trip
* Async chat: submit request now, poll for completion later

Reference:

* [M2M Chat (Sync)](/api-reference/endpoint/m2m-chat-sync)
* [M2M Chat (Async)](/api-reference/endpoint/m2m-chat-async)
* [M2M Chat Status](/api-reference/endpoint/m2m-chat-status)

### Session and analytics endpoints

Use these endpoints to observe real usage and integration quality.

Reference:

* [M2M Sessions](/api-reference/endpoint/m2m-sessions)
* [M2M Site Statistics](/api-reference/endpoint/m2m-site-statistics)

## Recommended implementation flow

For a new integration, use this sequence:

1. Authenticate with an API key
2. Validate tenant connectivity with a read request
3. Lock the correct `tenant_id` and `site_id` in configuration
4. Upload a small approved document set
5. Send a sync chat request as a smoke test
6. Add async chat if your workload needs queue-friendly handling
7. Collect feedback and read statistics to monitor quality

This flow keeps your first production rollout easy to verify.

## Sync chat vs async chat

### Sync chat

Use sync chat when:

* You need the answer immediately
* Request volume is moderate
* Your caller can wait for the response

Example request:

```json theme={null}
{
  "session_id": "user-123-web",
  "message": "How does the return process work?",
  "email": "user@example.com",
  "response_language": "en"
}
```

Typical sync response:

```json theme={null}
{
  "session_id": "user-123-web",
  "request_id": "req_abc123",
  "answer": "Returns are accepted within the published return window.",
  "confidence_level": "high",
  "confidence_score": 92
}
```

### Async chat

Use async chat when:

* You want non-blocking request handling
* Your application already uses job or queue patterns
* You need polling or background processing

Typical async sequence:

1. `POST /m2m/sites/{id}/chat/async`
2. Read `request_id`
3. Poll `GET /m2m/sites/{id}/chat/requests/{requestId}`
4. Stop polling when status is complete or failed

Initial async response:

```json theme={null}
{
  "request_id": "req_abc123",
  "session_id": "user-123-web",
  "status": "pending"
}
```

Status response after completion:

```json theme={null}
{
  "request_id": "req_abc123",
  "session_id": "user-123-web",
  "status": "completed",
  "answer": "Returns are accepted within the published return window."
}
```

## Session strategy

Choose a stable `session_id` strategy before going live.

Good examples:

* Per website visitor
* Per authenticated customer
* Per support thread
* Per messaging channel user

Keep the strategy stable enough that follow-up questions stay in the correct conversation context.

## Document strategy

Document quality directly affects answer quality.

Recommended document rollout:

1. Start with a small approved set
2. Prefer clean policy, support, and FAQ material
3. Review results before large-scale ingestion
4. Add Q\&A entries for repeated direct questions

Example text document payload:

```json theme={null}
{
  "title": "Support Hours",
  "content": "Support is available Monday to Friday between 09:00 and 18:00.",
  "category": "support"
}
```

Example Q\&A payload:

```json theme={null}
{
  "title": "Delivery FAQ",
  "question": "Do you offer same-day delivery?",
  "answer": "Availability depends on location and order timing.",
  "category": "faq"
}
```

## Error handling model

Use your HTTP client to separate retryable and non-retryable failures.

Typical handling:

* `400`: fix payload or request structure
* `401`: fix API key or authentication setup
* `403`: check plan, access, or allowed capability
* `404`: check tenant ID, site ID, or resource ownership
* `429`: retry with backoff
* `5xx`: use bounded retries and alerting

Do not blindly retry every failure class.

## Observability model

Track at minimum:

* Success and failure rate by endpoint
* Latency by endpoint
* `429` and `5xx` trends
* Async completion time
* Chat quality signals from feedback and statistics

If your integration is production-critical, add per-environment dashboards and alerts from day one.

## Suggested reading order

1. [API Authentication](/developer/api-authentication)
2. [M2M Code Samples](/developer/m2m-code-samples)
3. [M2M Integration Guidelines](/developer/m2m-best-practices)
4. [API Reference](/api-reference/introduction)