Endpoints

Complete list of SnackPrompt AI Engine API endpoints.

Authentication

All requests require authentication via the x-api-key header:

x-api-key: YOUR_API_KEY

To get your API Key, see the authentication documentation.

Summary

Endpoint	Method	Description
/v1/kb/elemental	POST	Ingest data into Knowledge Base
/v1/kb/elemental/{id}	DELETE	Remove data by ID
/v1/kb/delete	POST	Remove data by filters
/v1/kb/search	POST	Semantic search
/v1/kb/chat	POST	Chat with complete response
/v1/kb/chat/stream	POST	Chat with SSE streaming
/health	GET	Basic health check
/health/detailed	GET	Detailed health check

---

Ingestion

Ingest Elemental

Ingests an elemental (table/document) into the Knowledge Base. Runs in background.

POST /v1/kb/elemental

Request Body:

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

Response: 202 Accepted

{
  "status": "accepted",
  "message": "Ingestion started for {elemental_id}",
  "data": {
    "job_id": "trace-id",
    "elemental_id": "elemental-id"
  }
}

Example:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/elemental \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "elemental_id": "elem-123",
    "trace_id": "trace-001"
  }'

---

Removal

Remove by ID

Removes all data from a specific elemental.

DELETE /v1/kb/elemental/{elemental_id}

URL Parameters:

Parameter	Type	Description
elemental_id	string	ID of elemental to remove

Response: 200 OK

{
  "status": "success",
  "message": "Ingestion deleted for elemental_id: {elemental_id}",
  "data": {
    "elemental_id": "elemental-id"
  }
}

Example:

curl -X DELETE https://api-integrations.snackprompt.com/v1/kb/elemental/elem-123 \
  -H "x-api-key: YOUR_API_KEY"

---

Remove by Filters

Removes data using specific filters.

POST /v1/kb/delete

Request Body:

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

Important: The tenant_id is required.

Response: 200 OK

{
  "status": "success",
  "message": "Deletion completed",
  "data": {
    "filters": { ... }
  }
}

Example:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/delete \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "filters": {
      "tenant_id": "tenant-123",
      "source": "elemental"
    }
  }'

---

Search

Semantic Search

Performs semantic search on indexed data.

POST /v1/kb/search

Request Body:

{
  "query": "string",
  "filters": {
    "tenant_id": "string (required)",
    "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	object	Yes	Filters (tenant_id required)
limit	number	No	Maximum results (default: 10)

Response: 200 OK

{
  "items": [
    {
      "id": "uuid",
      "score": 0.85,
      "payload": {
        "tenant_id": "string",
        "snack_elemental_id": "string",
        "snack_item_id": "string",
        "original_text": "string",
        "tag_ids": ["string"],
        "tag_names": ["string"]
      }
    }
  ],
  "total_found": 5
}

Example:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "return policies",
    "filters": {
      "tenant_id": "tenant-123"
    },
    "limit": 5
  }'

---

Chat

Complete Chat

RAG chat that returns the complete response at once.

POST /v1/kb/chat

Request Body:

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

Response: 200 OK

{
  "answer": "AI-generated response...",
  "sources": [
    {
      "id": "uuid",
      "score": 0.85,
      "snack_item_id": "string",
      "snack_elemental_id": "string",
      "text": "Excerpt used as context...",
      "tag_ids": ["string"],
      "tag_names": ["string"]
    }
  ]
}

Example:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "what are the benefits of the premium plan?",
    "filters": {
      "tenant_id": "tenant-123"
    }
  }'

---

Streaming Chat

RAG chat via Server-Sent Events (SSE) for real-time responses.

POST /v1/kb/chat/stream

Request Body: Same as /v1/kb/chat

Response: text/event-stream

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

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

data: {"event":"message","data":{"content":" of the response..."}}

data: [DONE]

Events:

Event	Description
message	Content chunk
error	Error during streaming
[DONE]	End of stream

Response Headers:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

Example:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/chat/stream \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "explain product X",
    "filters": {
      "tenant_id": "tenant-123"
    }
  }' \
  --no-buffer

---

Observability

Health Check

Checks if the service is running.

GET /health

Response: 200 OK

{
  "status": "healthy"
}

---

Detailed Health Check

Checks service status and its dependencies.

GET /health/detailed

Response: 200 OK

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

---

Common Errors

Code	Error	Cause
400	Bad Request	Missing tenant_id or invalid parameters
404	Not Found	Resource not found
500	Internal Error	Internal server error

For details, see Error Codes.