# 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.


---

# 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/endpoints.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.