Data Models

Request and response schemas for the SnackPrompt AI Engine API.

Requests

IngestRequest

Used in POST /v1/kb/elemental

{
  "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

{
  "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

{
  "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

{
  "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.

{
  "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

{
  "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

{
  "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

{
  "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.

{
  "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.

{
  "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

{
  "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.

{
  "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:

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

Error event:

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

End of stream:

data: [DONE]

---

HealthResponse

Returned by GET /health

{
  "status": "healthy"
}

---

DetailedHealthResponse

Returned by GET /health/detailed

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

---

ErrorResponse

Returned in case of error.

{
  "detail": "string"
}

Or with validation details:

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