> 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/endpoints.md).

# 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](https://snack-prompt.gitbook.io/snack-prompt-docs/api-reference/authentication).

### 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:**

```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           |

**Response: `202 Accepted`**

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

**Example:**

```bash
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`**

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

**Example:**

```bash
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:**

```json
{
  "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`**

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

**Example:**

```bash
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:**

```json
{
  "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`**

```json
{
  "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:**

```bash
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:**

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

**Response: `200 OK`**

```json
{
  "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:**

```bash
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:**

```bash
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`**

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

***

#### Detailed Health Check

Checks service status and its dependencies.

```
GET /health/detailed
```

**Response: `200 OK`**

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