# Knowledge Retrieval API Guide

##  Request Endpoint

```
POST /external/use/seek-knowledge/seek HTTP/1.1
```

##  Request Available Model List

```
GET /external/use/seek-knowledge/models HTTP/1.1
```

## Request Headers

| Header          | Value                 | Description                                                                                      |
| --------------- | --------------------- | ------------------------------------------------------------------------------------------------ |
| `Authorization` | `Bearer <your_token>` | Authentication token for verifying user identity. Replace `<your_token>` with your actual token. |
| `Content-Type`  | `application/json`    | Indicates the request body is in JSON format.                                                    |
| `Host`          | `edge.flowith.net`    | API server address.                                                                              |
| `User-Agent`    | `HTTPie`              | (Optional) Client identifier.                                                                    |

## Request Body (JSON)

| Parameter  | Type         | Description                                                                          |
| ---------- | ------------ | ------------------------------------------------------------------------------------ |
| `messages` | Array        | Conversation message list. Each message object contains `role` and `content` fields. |
| `model`    | String       | Model name. Example: `"gpt-4o-mini"`                                                 |
| `stream`   | Boolean      | Enable streaming response? `true` to enable, `false` to disable.                     |
| `kb_list`  | String Array | Knowledge base ID list. Specifies the scope for knowledge retrieval.                 |

### **`messages` Field Details**

* `role`: Message role, can be `"assistant"` or `"user"`.
* `content`: Message content, such as sophisticated queries or instructions.

## Response

### **When `stream` is `true` (Streaming Response)**

* Response Status Code: `200 OK`
* Response Headers: Includes standard HTTP headers like `Content-Type: text/plain; charset=UTF-8`, etc.
* Response Body: Text stream starting with `data:`. Each `data:` block contains a JSON object with the following possible `tag` values:
  * `searching`: Indicates search in progress, `content` field includes progress updates.
  * `seeds`: Intermediate search results, `content` is a JSON array where each element is a piece of distinct knowledge containing `id`, `tokens`, `content`, `order`, `source_id`, `source_title`, and `nip`.
  * `final`: Indicates final results, `content` contains the complete response text.

### **When `stream` is `false`**

* Response Status Code: `200 OK`
* Response Headers: Includes standard HTTP headers like `Content-Type: application/json`, etc.
* Response Body: A JSON object containing `tag` and `content` fields.
  * `tag`: Always `"final"`.
  * `content`: Complete response text.

## `curl` Examples

### **Streaming Response (stream = true)**

```bash
curl -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [
      {"role": "assistant", "content": "I'd like to explore effective social dynamics and interpersonal relationships"},
      {"role": "user", "content": "Share your best strategies for authentic connection and building rapport in professional settings"}
    ],
    "model": "gpt-4.1-mini",
    "stream": true,
    "kb_list": ["<knowledge_base_id>"]
  }' 
```

### **Non-Streaming Response (stream = false)**

```bash
curl -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [
      {"role": "assistant", "content": "I'd like to explore effective social dynamics and interpersonal relationships"},
      {"role": "user", "content": "Share your best strategies for authentic connection and building rapport in professional settings"}
    ],
    "model": "gpt-4.1-mini",
    "stream": false,
    "kb_list": ["<knowledge_base_id>"]
  }' 
```

Remember to replace `<your_token>` and `<knowledge_base_id>` with your actual values.

## Rate Limits

* Requests: 12 requests per minute (RPM)
* Note: Exceeding this limit will result in HTTP 429 (Too Many Requests) errors

## Billing

* Quota Usage: Charges are calculated based on the Credits quota of the corresponding Flowith account
* Billing Cycle: Usage is calculated and deducted in real-time from your account balance