# 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"
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snackprompt.com/bring-your-data-into-ai/reference/data-models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.