# API Reference

The backend is a FastAPI application that serves REST APIs.

## Interactive API docs

When the stack is running, FastAPI provides OpenAPI specifications and Swagger UI at
`http://<HOST_IP>:4172/docs`

If you run the backend on a different host and port, edit accordingly.

## Route Summary

The backend defines the following application routes:

| Method | Path              | Description                                          |
| ------ | ----------------- | ---------------------------------------------------- |
| `GET`  | `/api/health`     | Returns application health status.                   |
| `GET`  | `/api/model`      | Returns the configured LLM model identifier.         |
| `POST` | `/api/chat`       | Streams chat responses from the RAG pipeline.        |
| `POST` | `/api/embeddings` | Creates and stores an embedding in the vector store. |

## API Endpoints

### `GET /api/health`

Returns a simple health payload to confirm that the application is running.

**Response**

```json
{
  "status": "healthy",
  "message": "Live Video Captioning RAG application is up and running."
}
```

### `GET /api/model`

Returns the configured LLM model ID used by the backend.

**Response**

```json
{
  "status": "Success",
  "llm_model": "<configured-model-id>"
}
```

### `POST /api/chat`

Submits a user question to the RAG pipeline and returns a streamed response using Server-Sent Events.

**Request body**

```json
{
  "input": "What you see in the image?"
}
```

**Success response**

- Content type: `text/event-stream`
- Body: streamed output generated by the RAG chain

**Validation error**

Returned when `input` is missing or an empty string.

```json
{
  "detail": "Input question is required and cannot be empty."
}
```

### `POST /api/embeddings`

Processes caption or image-derived content and stores the resulting embedding in the VDMS vector store.

**Request body**

```json
{
  "image_data": "<base64-or-caption-payload>",
  "metadata": {
    "result": "The image shows ....<caption_text>",
    "timestamp": 2754121008,
    "timestamp_seconds": 2.75,
    "resolution": {
      "height": 1080,
      "width": 1920
    },
    "frame_id": 101,
    "img_format": "BGR"
  }
}
```

**Success response**

```json
{
  "status": "success",
  "message": "Embedding processed and stored successfully.",
  "id": "<embedding-id>"
}
```

**Validation errors**

Returned when:

- `image_data` is missing, empty, or has whitespace only
- `metadata` is not a JSON object
- the embedding service rejects the payload with a `ValueError`

Example validation response:

```json
{
  "detail": "Input image data is required and cannot be empty."
}
```

**Server error**

If embedding processing fails unexpectedly, the backend returns:

```json
{
  "detail": "Failed to process embedding."
}
```

## Learn More

- [Get Started](./get-started.md)
- [Known Issues](./known-issues.md)