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

# API Overview

> Overview of the Notvis Connect REST API.

## Base URL

```
https://api.notvis.com/v1
```

## Content Type

All requests must include `Content-Type: application/json`. Request bodies must be valid JSON. Maximum request body size is **1 MB**.

## Authentication

Most endpoints require an API key passed via the `Authorization` header:

```
Authorization: Bearer nc_live_your_api_key
```

See [Authentication](/authentication) for details.

## Idempotency

Include an `Idempotency-Key` header on POST requests to safely retry without creating duplicates. See [Idempotency](/idempotency).

## Endpoints

### Email

| Method | Endpoint                   | Description                  |
| ------ | -------------------------- | ---------------------------- |
| POST   | `/v1/emails/messages`      | Send a transactional email   |
| GET    | `/v1/emails/messages/{id}` | Get email status and details |

### SMS

| Method | Endpoint                | Description                            |
| ------ | ----------------------- | -------------------------------------- |
| POST   | `/v1/sms/messages`      | Send SMS (single or batch up to 1,000) |
| GET    | `/v1/sms/messages/{id}` | Get SMS status and details             |

### Push Notifications

| Method | Endpoint            | Auth | Description                              |
| ------ | ------------------- | ---- | ---------------------------------------- |
| POST   | `/v1/push/register` | No   | Register a device for push notifications |
| POST   | `/v1/push/identify` | No   | Link a device to an identified user      |

### Health

| Method | Endpoint   | Description                                       |
| ------ | ---------- | ------------------------------------------------- |
| GET    | `/healthz` | Liveness check — always returns 200               |
| GET    | `/readyz`  | Readiness check — 200 if all dependencies healthy |

## Request IDs

Every response includes an `X-Request-ID` header. You can also send your own `X-Request-ID` to correlate requests. Include this ID when contacting support.

## Status Lifecycle

### Email

```
queued → sending → sent → delivered
                       → bounced
                       → failed
```

### SMS

```
queued → sending → sent → delivered
                       → undelivered
                       → failed
                       → expired
```

Scheduled messages start with status `scheduled` and move to `queued` at the scheduled time.