# 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


---

# 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://doc.flowith.io/knowledge-garden/knowledge-retrieval-api-guide.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.