OpenSource
/
ragflow
Watch 4
Star 0
Fork 0
Code Issues 0 Pull Requests 0 Releases 33 Wiki Activity
Browse Source

Docs: Update HTTP API reference with simplified response format and parameters (#9454) 

### What problem does this PR solve?

- Make `session_id` optional and add `inputs` parameter
- Remove deprecated `sync_dsl` parameter
- Update request/response examples to match current API behavior

### Type of change

- [x] Documentation Update
tags/v0.20.2
Liu An 2 months ago
parent
5e8cd693a5
commit
3d645ff31a
No account linked to committer's email address
1 changed files with 295 additions and 227 deletions
Unified View Show Diff Stats
  1. 295
    227
      docs/references/http_api_reference.md

+ 295
- 227
docs/references/http_api_reference.md View File

Stream: Stream:


```json ```json
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
data:{
"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
"choices": [ "choices": [
{ {
"delta": { "delta": {
"content": "This is a test. If you have any specific questions or need information, feel",
"content": "Hello! It seems like you're just greeting me. If you have a specific",
"role": "assistant", "role": "assistant",
"function_call": null, "function_call": null,
"tool_calls": null
"tool_calls": null,
"reasoning_content": null
}, },
"finish_reason": null, "finish_reason": null,
"index": 0, "index": 0,
"logprobs": null "logprobs": null
} }
], ],
"created": 1740543996,
"created": 1755084508,
"model": "model", "model": "model",
"object": "chat.completion.chunk", "object": "chat.completion.chunk",
"system_fingerprint": "", "system_fingerprint": "",
"usage": null "usage": null
} }
// omit duplicated information
{"choices":[{"delta":{"content":" free to ask, and I will do my best to provide an answer based on","role":"assistant"}}]}
{"choices":[{"delta":{"content":" the knowledge I have. If your question is unrelated to the provided knowledge base,","role":"assistant"}}]}
{"choices":[{"delta":{"content":" I will let you know.","role":"assistant"}}]}
// the last chunk
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
"choices": [
{
"delta": {
"content": null,
"role": "assistant",
"function_call": null,
"tool_calls": null
},
"finish_reason": "stop",
"index": 0,
"logprobs": null
}
],
"created": 1740543996,
"model": "model",
"object": "chat.completion.chunk",
"system_fingerprint": "",
"usage": {
"prompt_tokens": 18,
"completion_tokens": 225,
"total_tokens": 243
}
}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " question or need information, feel free to ask, and I'll do my best", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " to assist you based on the knowledge base provided.", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": null, "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": "stop", "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": {"prompt_tokens": 5, "completion_tokens": 188, "total_tokens": 193}}

data:[DONE]
``` ```


Non-stream: Non-stream:


```json ```json
{ {
"choices":[
"choices": [
{ {
"finish_reason":"stop",
"index":0,
"logprobs":null,
"message":{
"content":"This is a test. If you have any specific questions or need information, feel free to ask, and I will do my best to provide an answer based on the knowledge I have. If your question is unrelated to the provided knowledge base, I will let you know.",
"role":"assistant"
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "Hello! I'm your smart assistant. What can I do for you?",
"role": "assistant"
} }
} }
], ],
"created":1740543499,
"id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
"model":"model",
"object":"chat.completion",
"usage":{
"completion_tokens":246,
"completion_tokens_details":{
"accepted_prediction_tokens":246,
"reasoning_tokens":18,
"rejected_prediction_tokens":0
"created": 1755084403,
"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
"model": "model",
"object": "chat.completion",
"usage": {
"completion_tokens": 55,
"completion_tokens_details": {
"accepted_prediction_tokens": 55,
"reasoning_tokens": 5,
"rejected_prediction_tokens": 0
}, },
"prompt_tokens":18,
"total_tokens":264
"prompt_tokens": 5,
"total_tokens": 60
} }
} }
``` ```



Failure: Failure:


```json ```json
Stream: Stream:


```json ```json
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
"choices": [
{
"delta": {
"content": "This is a test. If you have any specific questions or need information, feel",
"role": "assistant",
"function_call": null,
"tool_calls": null
},
"finish_reason": null,
"index": 0,
"logprobs": null
}
],
"created": 1740543996,
"model": "model",
data: {
"id": "5fa65c94-e316-4954-800a-06dfd5827052",
"object": "chat.completion.chunk", "object": "chat.completion.chunk",
"system_fingerprint": "",
"usage": null
}
// omit duplicated information
{"choices":[{"delta":{"content":" free to ask, and I will do my best to provide an answer based on","role":"assistant"}}]}
{"choices":[{"delta":{"content":" the knowledge I have. If your question is unrelated to the provided knowledge base,","role":"assistant"}}]}
{"choices":[{"delta":{"content":" I will let you know.","role":"assistant"}}]}
// the last chunk
{
"id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
"model": "99ee29d6783511f09c921a6272e682d8",
"choices": [ "choices": [
{ {
"delta": { "delta": {
"content": null,
"role": "assistant",
"function_call": null,
"tool_calls": null
"content": "Hello"
}, },
"finish_reason": "stop",
"index": 0,
"logprobs": null
"finish_reason": null,
"index": 0
} }
],
"created": 1740543996,
"model": "model",
"object": "chat.completion.chunk",
"system_fingerprint": "",
"usage": {
"prompt_tokens": 18,
"completion_tokens": 225,
"total_tokens": 243
}
]
} }

data: {"id": "518022d9-545b-4100-89ed-ecd9e46fa753", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": "!"}, "finish_reason": null, "index": 0}]}

data: {"id": "f37c4af0-8187-4c86-8186-048c3c6ffe4e", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " How"}, "finish_reason": null, "index": 0}]}

data: {"id": "3ebc0fcb-0f85-4024-b4a5-3b03234a16df", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " can"}, "finish_reason": null, "index": 0}]}

data: {"id": "efa1f3cf-7bc4-47a4-8e53-cd696f290587", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " I"}, "finish_reason": null, "index": 0}]}

data: {"id": "2eb6f741-50a3-4d3d-8418-88be27895611", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " assist"}, "finish_reason": null, "index": 0}]}

data: {"id": "f1227e4f-bf8b-462c-8632-8f5269492ce9", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " you"}, "finish_reason": null, "index": 0}]}

data: {"id": "35b669d0-b2be-4c0c-88d8-17ff98592b21", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " today"}, "finish_reason": null, "index": 0}]}

data: {"id": "f00d8a39-af60-4f32-924f-d64106a7fdf1", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": "?"}, "finish_reason": null, "index": 0}]}

data: [DONE]
``` ```


Non-stream: Non-stream:


```json ```json
{ {
"choices":[
"choices": [
{ {
"finish_reason":"stop",
"index":0,
"logprobs":null,
"message":{
"content":"This is a test. If you have any specific questions or need information, feel free to ask, and I will do my best to provide an answer based on the knowledge I have. If your question is unrelated to the provided knowledge base, I will let you know.",
"role":"assistant"
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "Hello! How can I assist you today?",
"role": "assistant"
} }
} }
], ],
"created":1740543499,
"id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
"model":"model",
"object":"chat.completion",
"usage":{
"completion_tokens":246,
"completion_tokens_details":{
"accepted_prediction_tokens":246,
"reasoning_tokens":18,
"rejected_prediction_tokens":0
"created": null,
"id": "17aa4ec5-6d36-40c6-9a96-1b069c216d59",
"model": "99ee29d6783511f09c921a6272e682d8",
"object": "chat.completion",
"param": null,
"usage": {
"completion_tokens": 9,
"completion_tokens_details": {
"accepted_prediction_tokens": 0,
"reasoning_tokens": 0,
"rejected_prediction_tokens": 0
}, },
"prompt_tokens":18,
"total_tokens":264
"prompt_tokens": 1,
"total_tokens": 10
} }
} }
``` ```



Failure: Failure:


```json ```json


```bash ```bash
curl --request PUT \ curl --request PUT \
--url http://{address}/api/v1/datasets/{dataset_id}/info/{document_id} \
--url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
--header 'Authorization: Bearer <YOUR_API_KEY>' \ --header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--data ' --data '
- In streaming mode, not all responses include a reference, as this depends on the system's judgement. - In streaming mode, not all responses include a reference, as this depends on the system's judgement.
- In streaming mode, the last message is an empty message: - In streaming mode, the last message is an empty message:


```json
data:
{
"code": 0,
"data": true
}
```
[DONE]
``` ```


::: :::
- Body: - Body:
- `"question"`: `string` - `"question"`: `string`
- `"stream"`: `boolean` - `"stream"`: `boolean`
- `"session_id"`: `string`
- `"session_id"`: `string`(optional)
- `"inputs"`: `object`(optional)
- `"user_id"`: `string`(optional) - `"user_id"`: `string`(optional)
- `"sync_dsl"`: `boolean` (optional)
- other parameters: `string`


:::info IMPORTANT :::info IMPORTANT
You can include custom parameters in the request body, but first ensure they are defined in the [Begin](../guides/agent/agent_component_reference/begin.mdx) agent component. You can include custom parameters in the request body, but first ensure they are defined in the [Begin](../guides/agent/agent_component_reference/begin.mdx) agent component.


##### Request example ##### Request example


- If the **Begin** component does not take parameters, the following code will create a session.
- If the **Begin** component does not take parameters.


```bash ```bash
curl --request POST \ curl --request POST \
--header 'Authorization: Bearer <YOUR_API_KEY>' \ --header 'Authorization: Bearer <YOUR_API_KEY>' \
--data-binary ' --data-binary '
{ {
"question": "Hello",
"stream": false,
}' }'
``` ```


- If the **Begin** component takes parameters, the following code will create a session.
- If the **Begin** component takes parameters.


```bash ```bash
curl --request POST \ curl --request POST \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \ --header 'Authorization: Bearer <YOUR_API_KEY>' \
--data-binary ' --data-binary '
{
"lang":"English",
"file":"How is the weather tomorrow?"
}'
{
"question": "Hello",
"stream": false,
"inputs": {
"line_var": {
"type": "line",
"value": "I am line_var"
},
"int_var": {
"type": "integer",
"value": 1
},
"paragraph_var": {
"type": "paragraph",
"value": "a\nb\nc"
},
"option_var": {
"type": "options",
"value": "option 2"
},
"boolean_var": {
"type": "boolean",
"value": true
}
}
}'
``` ```


The following code will execute the completion process The following code will execute the completion process
- `false`: Disable streaming. - `false`: Disable streaming.
- `"session_id"`: (*Body Parameter*) - `"session_id"`: (*Body Parameter*)
The ID of the session. If it is not provided, a new session will be generated. The ID of the session. If it is not provided, a new session will be generated.
- `"inputs"`: (*Body Parameter*)
Parameters specified in the **Begin** component.
- `"user_id"`: (*Body parameter*), `string` - `"user_id"`: (*Body parameter*), `string`
The optional user-defined ID. Valid *only* when no `session_id` is provided. The optional user-defined ID. Valid *only* when no `session_id` is provided.
- `"sync_dsl"`: (*Body parameter*), `boolean`
Whether to synchronize the changes to existing sessions when an agent is modified, defaults to `false`.
- Other parameters: (*Body Parameter*)
Parameters specified in the **Begin** component.


#### Response #### Response


success without `session_id` provided and with no parameters specified in the **Begin** component: success without `session_id` provided and with no parameters specified in the **Begin** component:


Stream:

```json ```json
data:{ data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
"created_at": 1755083342,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": { "data": {
"answer": "Hi! I'm your smart assistant. What can I do for you?",
"reference": {},
"id": "31e6091d-88d4-441b-ac65-eae1c055be7b",
"session_id": "2987ad3eb85f11efb2a70242ac120005"
}
"content": "Hello"
},
"session_id": "eaf19a8e783511f0b9b61a6272e682d8"
}

data:{
"event": "message",
"message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
"created_at": 1755083342,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"content": "!"
},
"session_id": "eaf19a8e783511f0b9b61a6272e682d8"
} }

data:{ data:{
"code": 0,
"message": "",
"data": true
"event": "message",
"message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
"created_at": 1755083342,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": {
"content": " How"
},
"session_id": "eaf19a8e783511f0b9b61a6272e682d8"
} }

...

data:[DONE]
``` ```


Success without `session_id` provided and with parameters specified in the **Begin** component:
Non-stream:


```json ```json
data:{
{
"code": 0, "code": 0,
"message": "",
"data": { "data": {
"session_id": "eacb36a0bdff11ef97120242ac120006",
"answer": "",
"reference": [],
"param": [
{
"key": "lang",
"name": "Target Language",
"optional": false,
"type": "line",
"value": "English"
},
{
"key": "file",
"name": "Files",
"optional": false,
"type": "file",
"value": "How is the weather tomorrow?"
},
{
"key": "hhyt",
"name": "hhty",
"optional": true,
"type": "line"
"created_at": 1755083440,
"data": {
"created_at": 547061.147866385,
"elapsed_time": 2.595433341921307,
"inputs": {},
"outputs": {
"_created_time": 547061.149137775,
"_elapsed_time": 8.720310870558023e-05,
"content": "Hello! How can I assist you today?"
} }
]
},
"event": "workflow_finished",
"message_id": "25807f94783611f095171a6272e682d8",
"session_id": "25663198783611f095171a6272e682d8",
"task_id": "99ee29d6783511f09c921a6272e682d8"
} }
} }
data:
``` ```


Success with parameters specified in the **Begin** component:
Success without `session_id` provided and with parameters specified in the **Begin** component:

Stream:


```json ```json
data:{ data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "0e273472783711f0806e1a6272e682d8",
"created_at": 1755083830,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": { "data": {
"answer": "How",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "Hello"
},
"session_id": "0e0d1542783711f0806e1a6272e682d8"
} }

data:{ data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "0e273472783711f0806e1a6272e682d8",
"created_at": 1755083830,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": { "data": {
"answer": "How is",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "!"
},
"session_id": "0e0d1542783711f0806e1a6272e682d8"
} }

data:{ data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "0e273472783711f0806e1a6272e682d8",
"created_at": 1755083830,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": { "data": {
"answer": "How is the",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": " How"
},
"session_id": "0e0d1542783711f0806e1a6272e682d8"
} }
data:{

...

data:[DONE]
```

Non-stream:

```json
{
"code": 0, "code": 0,
"message": "",
"data": { "data": {
"answer": "How is the weather",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
"created_at": 1755083779,
"data": {
"created_at": 547400.868004651,
"elapsed_time": 3.5037803899031132,
"inputs": {
"boolean_var": {
"type": "boolean",
"value": true
},
"int_var": {
"type": "integer",
"value": 1
},
"line_var": {
"type": "line",
"value": "I am line_var"
},
"option_var": {
"type": "options",
"value": "option 2"
},
"paragraph_var": {
"type": "paragraph",
"value": "a\nb\nc"
}
},
"outputs": {
"_created_time": 547400.869271305,
"_elapsed_time": 0.0001251999055966735,
"content": "Hello there! How can I assist you today?"
}
},
"event": "workflow_finished",
"message_id": "effdad8c783611f089261a6272e682d8",
"session_id": "efe523b6783611f089261a6272e682d8",
"task_id": "99ee29d6783511f09c921a6272e682d8"
} }
} }
```

Success with parameters specified in the **Begin** component:

Stream:

```json
data:{ data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "5b62e790783711f0bc531a6272e682d8",
"created_at": 1755083960,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": { "data": {
"answer": "How is the weather tomorrow",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "Hello"
},
"session_id": "979e450c781d11f095cb729e3aa55728"
} }

data:{ data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "5b62e790783711f0bc531a6272e682d8",
"created_at": 1755083960,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": { "data": {
"answer": "How is the weather tomorrow?",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": "!"
},
"session_id": "979e450c781d11f095cb729e3aa55728"
} }

data:{ data:{
"code": 0,
"message": "",
"event": "message",
"message_id": "5b62e790783711f0bc531a6272e682d8",
"created_at": 1755083960,
"task_id": "99ee29d6783511f09c921a6272e682d8",
"data": { "data": {
"answer": "How is the weather tomorrow?",
"reference": {},
"id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
"session_id": "4399c7d0b86311efac5b0242ac120005"
}
"content": " You"
},
"session_id": "979e450c781d11f095cb729e3aa55728"
} }
data:{

...

data:[DONE]
```

Non-stream:

```json
{
"code": 0, "code": 0,
"message": "",
"data": true
"data": {
"created_at": 1755084029,
"data": {
"created_at": 547650.750818867,
"elapsed_time": 1.6227330720284954,
"inputs": {},
"outputs": {
"_created_time": 547650.752800839,
"_elapsed_time": 9.628792759031057e-05,
"content": "Hello! It appears you've sent another \"Hello\" without additional context. I'm here and ready to respond to any requests or questions you may have. Is there something specific you'd like to discuss or learn about?"
}
},
"event": "workflow_finished",
"message_id": "84eec534783711f08db41a6272e682d8",
"session_id": "979e450c781d11f095cb729e3aa55728",
"task_id": "99ee29d6783511f09c921a6272e682d8"
}
} }
``` ```



Write Preview
Loading…
Cancel
Save