> For the complete documentation index, see [llms.txt](https://docs.snackprompt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snackprompt.com/bring-your-data-into-ai/reference/data-models.md).

# Data Models

Request and response schemas for the SnackPrompt AI Engine API.

### Requests

#### IngestRequest

Used in `POST /v1/kb/elemental`

```json
{
  "elemental_id": "string",
  "trace_id": "string (optional)"
}
```

| Field          | Type   | Required | Description               |
| -------------- | ------ | -------- | ------------------------- |
| `elemental_id` | string | Yes      | ID of elemental to ingest |
| `trace_id`     | string | No       | ID for tracking           |

***

#### SearchRequest

Used in `POST /v1/kb/search`

```json
{
  "query": "string",
  "filters": {
    "tenant_id": "string",
    "elemental_id": "string (optional)",
    "user_id": "string (optional)",
    "tag_ids": ["string"],
    "tag_names": ["string"],
    "source": "string (optional)",
    "type_name": "string (optional)",
    "category_name": "string (optional)"
  },
  "limit": 10
}
```

| Field     | Type    | Required | Description                   |
| --------- | ------- | -------- | ----------------------------- |
| `query`   | string  | Yes      | Search text                   |
| `filters` | Filters | Yes      | Filters object                |
| `limit`   | number  | No       | Maximum results (default: 10) |

***

#### ChatRequest

Used in `POST /v1/kb/chat` and `POST /v1/kb/chat/stream`

```json
{
  "query": "string",
  "filters": {
    "tenant_id": "string",
    "elemental_id": "string (optional)",
    "user_id": "string (optional)",
    "tag_ids": ["string"],
    "tag_names": ["string"]
  }
}
```

| Field     | Type    | Required | Description    |
| --------- | ------- | -------- | -------------- |
| `query`   | string  | Yes      | User question  |
| `filters` | Filters | Yes      | Filters object |

***

#### DeleteRequest

Used in `POST /v1/kb/delete`

```json
{
  "filters": {
    "tenant_id": "string",
    "elemental_id": "string (optional)",
    "user_id": "string (optional)",
    "tag_ids": ["string"],
    "tag_names": ["string"],
    "source": "string (optional)"
  }
}
```

| Field     | Type    | Required | Description                          |
| --------- | ------- | -------- | ------------------------------------ |
| `filters` | Filters | Yes      | Filters object (tenant\_id required) |

***

#### Filters

Filters object used in various requests.

```json
{
  "tenant_id": "string",
  "elemental_id": "string (optional)",
  "user_id": "string (optional)",
  "tag_ids": ["string"],
  "tag_names": ["string"],
  "source": "elemental | document | file",
  "type_name": "string (optional)",
  "category_name": "string (optional)"
}
```

| Field           | Type      | Required | Description    |
| --------------- | --------- | -------- | -------------- |
| `tenant_id`     | string    | **Yes**  | Tenant ID      |
| `elemental_id`  | string    | No       | Elemental ID   |
| `user_id`       | string    | No       | User ID        |
| `tag_ids`       | string\[] | No       | Tag IDs (OR)   |
| `tag_names`     | string\[] | No       | Tag names (OR) |
| `source`        | string    | No       | Source type    |
| `type_name`     | string    | No       | Elemental type |
| `category_name` | string    | No       | Category       |

***

### Responses

#### IngestResponse

Returned by `POST /v1/kb/elemental`

```json
{
  "status": "accepted",
  "message": "Ingestion started for {elemental_id}",
  "data": {
    "job_id": "string",
    "elemental_id": "string"
  }
}
```

| Field               | Type   | Description                     |
| ------------------- | ------ | ------------------------------- |
| `status`            | string | Operation status (`accepted`)   |
| `message`           | string | Descriptive message             |
| `data.job_id`       | string | Job ID (trace\_id or generated) |
| `data.elemental_id` | string | ID of elemental being ingested  |

***

#### DeleteResponse

Returned by `DELETE /v1/kb/elemental/{id}` and `POST /v1/kb/delete`

```json
{
  "status": "success",
  "message": "Deletion completed",
  "data": {
    "elemental_id": "string",
    "filters": {}
  }
}
```

| Field     | Type   | Description                  |
| --------- | ------ | ---------------------------- |
| `status`  | string | Operation status (`success`) |
| `message` | string | Descriptive message          |
| `data`    | object | Operation details            |

***

#### SearchResponse

Returned by `POST /v1/kb/search`

```json
{
  "items": [
    {
      "id": "string (uuid)",
      "score": 0.85,
      "payload": {
        "tenant_id": "string",
        "user_id": "string",
        "snack_elemental_id": "string",
        "snack_column_id": "string",
        "snack_item_id": "string",
        "source": "string",
        "type_name": "string",
        "category_name": "string",
        "original_text": "string",
        "tag_ids": ["string"],
        "tag_names": ["string"]
      }
    }
  ],
  "total_found": 5
}
```

| Field         | Type          | Description         |
| ------------- | ------------- | ------------------- |
| `items`       | SearchItem\[] | Results list        |
| `total_found` | number        | Total results found |

***

#### SearchItem

Individual search result item.

```json
{
  "id": "string (uuid)",
  "score": 0.85,
  "payload": {
    "tenant_id": "string",
    "user_id": "string",
    "snack_elemental_id": "string",
    "snack_column_id": "string",
    "snack_item_id": "string",
    "source": "string",
    "type_name": "string",
    "category_name": "string",
    "original_text": "string",
    "tag_ids": ["string"],
    "tag_names": ["string"]
  }
}
```

| Field     | Type        | Description             |
| --------- | ----------- | ----------------------- |
| `id`      | string      | UUID of point in Qdrant |
| `score`   | number      | Similarity score (0-1)  |
| `payload` | ItemPayload | Item metadata           |

***

#### ItemPayload

Metadata stored with each chunk.

```json
{
  "tenant_id": "string",
  "user_id": "string",
  "snack_elemental_id": "string",
  "snack_column_id": "string",
  "snack_item_id": "string",
  "source": "elemental | document | file",
  "type_name": "string",
  "category_name": "string",
  "original_text": "string",
  "tag_ids": ["string"],
  "tag_names": ["string"]
}
```

| Field                | Type      | Description               |
| -------------------- | --------- | ------------------------- |
| `tenant_id`          | string    | Tenant ID                 |
| `user_id`            | string    | User ID                   |
| `snack_elemental_id` | string    | Source elemental ID       |
| `snack_column_id`    | string    | Column ID (if applicable) |
| `snack_item_id`      | string    | Item ID                   |
| `source`             | string    | Source type               |
| `type_name`          | string    | Elemental type            |
| `category_name`      | string    | Category                  |
| `original_text`      | string    | Original content          |
| `tag_ids`            | string\[] | Tag IDs                   |
| `tag_names`          | string\[] | Tag names                 |

***

#### ChatResponse

Returned by `POST /v1/kb/chat`

```json
{
  "answer": "string",
  "sources": [
    {
      "id": "string (uuid)",
      "score": 0.85,
      "snack_item_id": "string",
      "snack_elemental_id": "string",
      "text": "string",
      "tag_ids": ["string"],
      "tag_names": ["string"]
    }
  ]
}
```

| Field     | Type          | Description         |
| --------- | ------------- | ------------------- |
| `answer`  | string        | AI-generated answer |
| `sources` | ChatSource\[] | Sources used        |

***

#### ChatSource

Source used to generate chat response.

```json
{
  "id": "string (uuid)",
  "score": 0.85,
  "snack_item_id": "string",
  "snack_elemental_id": "string",
  "text": "string",
  "tag_ids": ["string"],
  "tag_names": ["string"]
}
```

| Field                | Type      | Description             |
| -------------------- | --------- | ----------------------- |
| `id`                 | string    | UUID of point in Qdrant |
| `score`              | number    | Similarity score        |
| `snack_item_id`      | string    | Source item ID          |
| `snack_elemental_id` | string    | Source elemental ID     |
| `text`               | string    | Excerpt used as context |
| `tag_ids`            | string\[] | Tag IDs                 |
| `tag_names`          | string\[] | Tag names               |

***

#### ChatStreamEvent

SSE event returned by `POST /v1/kb/chat/stream`

**Message event:**

```json
{
  "event": "message",
  "data": {
    "content": "string"
  }
}
```

**Error event:**

```json
{
  "event": "error",
  "data": {
    "message": "string"
  }
}
```

**End of stream:**

```
data: [DONE]
```

***

#### HealthResponse

Returned by `GET /health`

```json
{
  "status": "healthy"
}
```

***

#### DetailedHealthResponse

Returned by `GET /health/detailed`

```json
{
  "status": "healthy",
  "dependencies": {
    "qdrant": "healthy",
    "jina": "healthy"
  },
  "system": {
    "memory_usage": "45%",
    "cpu_usage": "12%"
  }
}
```

***

#### ErrorResponse

Returned in case of error.

```json
{
  "detail": "string"
}
```

Or with validation details:

```json
{
  "detail": [
    {
      "loc": ["body", "field"],
      "msg": "error message",
      "type": "error_type"
    }
  ]
}
```