gistfile1.txt

# API Documentation: `POST /api/v1/visits`

Create a new visit by uploading an audio file, specifying a note template, and optionally providing a webhook URL for asynchronous processing.

---

## Authentication

- **API Key Required**
  - Include your API key in the `X-Api-Key` header.
  - **How to get an API key:**
    1. Log in to your account.
    2. Go to **Settings** > **API Keys**.
    3. Create and copy your API key.

---

## Request Parameters

Send a JSON or form-encoded payload with the following parameters:

| Parameter      | Type   | Required | Description                                                                                 |
|---------------|--------|----------|---------------------------------------------------------------------------------------------|
| `template_id`  | int    | Yes      | The ID of the NoteTemplate to use. You can create or view NoteTemplates in the web frontend. |
| `audio_file`   | string | Yes      | The audio file, base64-encoded, prefixed with the MIME type (e.g., `data:audio/mp3;base64,...`). |
| `webhook_url`  | string | No       | (Optional) A URL to receive a POST callback when processing is complete.                     |

### How to get a NoteTemplate ID
- You can create or view NoteTemplates in the web frontend. Use the ID of the template you want to use for the visit.

---

## Example Request

```http
POST /api/v1/visits
Headers:
  X-Api-Key: YOUR_API_KEY

Body (JSON):
{
  "template_id": 123,
  "audio_file": "data:audio/mp3;base64,AAAAGGZ0eXBtc...",
  "webhook_url": "https://example.com/webhook"
}
```

---

## Webhook URL

If you provide a `webhook_url`, the system will send a POST request to that URL when the visit processing is complete.

### Webhook Request
- **Method:** POST
- **Content-Type:** application/json

#### Example Webhook Payload

```json
{
  "notes": "The generated note text as a string.",
  "encounter_uuid": "abc123-uuid"
}
```

- `notes`: The generated notes for the visit, formatted as a string.
- `encounter_uuid`: The unique identifier for the created encounter/visit.

---

## Response

- **201 Created**
  - On success, returns a JSON object with the `encounter_uuid` of the created visit.

#### Example Success Response

```json
{
  "encounter_uuid": "abc123-uuid"
}
```

---

**Notes:**
- The `template_id` must correspond to a valid NoteTemplate. You can create and manage NoteTemplates in the web frontend.
- The `audio_file` must be a valid base64-encoded audio file, prefixed with the correct MIME type.
- The `webhook_url` is optional but recommended for asynchronous processing.