Knowledge Retrieval API Guide

This document will help you quickly master and effectively use the Knowledge Retrieval API. Through this API, you can send messages to the model and retrieve relevant knowledge.

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)

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)

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