Skip to content

Commit 8760feb

Browse files
tisniktisnik
authored
Merge pull request lightspeed-core#798 from tisnik/lcore-946-updated-rest-api-documentation
LCORE-946: updated REST API documentation
2 parents 50657cf + 8d2a657 commit 8760feb

3 files changed

Lines changed: 165 additions & 15 deletions

File tree

‎docs/openapi.json‎

Lines changed: 87 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -411,7 +411,7 @@
411411
"streaming_query"
412412
],
413413
"summary": "Streaming Query Endpoint Handler",
414-
"description": "Handle request to the /streaming_query endpoint.\n\nThis endpoint receives a query request, authenticates the user,\nselects the appropriate model and provider, and streams\nincremental response events from the Llama Stack backend to the\nclient. Events include start, token updates, tool calls, turn\ncompletions, errors, and end-of-stream metadata. Optionally\nstores the conversation transcript if enabled in configuration.\n\nReturns:\n StreamingResponse: An HTTP streaming response yielding\n SSE-formatted events for the query lifecycle.\n\nRaises:\n HTTPException: Returns HTTP 500 if unable to connect to the\n Llama Stack server.",
414+
"description": "Handle request to the /streaming_query endpoint using Agent API.\n\nThis is a wrapper around streaming_query_endpoint_handler_base that provides\nthe Agent API specific retrieve_response and response generator functions.\n\nReturns:\n StreamingResponse: An HTTP streaming response yielding\n SSE-formatted events for the query lifecycle.\n\nRaises:\n HTTPException: Returns HTTP 500 if unable to connect to the\n Llama Stack server.",
415415
"operationId": "streaming_query_endpoint_handler_v1_streaming_query_post",
416416
"requestBody": {
417417
"content": {
@@ -1306,6 +1306,92 @@
13061306
}
13071307
}
13081308
},
1309+
"/v2/streaming_query": {
1310+
"post": {
1311+
"tags": [
1312+
"streaming_query_v2"
1313+
],
1314+
"summary": "Streaming Query Endpoint Handler V2",
1315+
"description": "Handle request to the /streaming_query endpoint using Responses API.\n\nThis is a wrapper around streaming_query_endpoint_handler_base that provides\nthe Responses API specific retrieve_response and response generator functions.\n\nReturns:\n StreamingResponse: An HTTP streaming response yielding\n SSE-formatted events for the query lifecycle.\n\nRaises:\n HTTPException: Returns HTTP 500 if unable to connect to the\n Llama Stack server.",
1316+
"operationId": "streaming_query_endpoint_handler_v2_v2_streaming_query_post",
1317+
"requestBody": {
1318+
"content": {
1319+
"application/json": {
1320+
"schema": {
1321+
"$ref": "#/components/schemas/QueryRequest"
1322+
}
1323+
}
1324+
},
1325+
"required": true
1326+
},
1327+
"responses": {
1328+
"200": {
1329+
"description": "Streaming response with Server-Sent Events",
1330+
"content": {
1331+
"application/json": {
1332+
"schema": {
1333+
"type": "string",
1334+
"example": "data: {\"event\": \"start\", \"data\": {\"conversation_id\": \"123e4567-e89b-12d3-a456-426614174000\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 0, \"token\": \"Hello\"}}\n\ndata: {\"event\": \"end\", \"data\": {\"referenced_documents\": [], \"truncated\": null, \"input_tokens\": 0, \"output_tokens\": 0}, \"available_quotas\": {}}\n\n"
1335+
}
1336+
},
1337+
"text/plain": {
1338+
"schema": {
1339+
"type": "string",
1340+
"example": "Hello world!\n\n---\n\nReference: https://example.com/doc"
1341+
}
1342+
}
1343+
}
1344+
},
1345+
"400": {
1346+
"description": "Missing or invalid credentials provided by client",
1347+
"content": {
1348+
"application/json": {
1349+
"schema": {
1350+
"$ref": "#/components/schemas/UnauthorizedResponse"
1351+
}
1352+
}
1353+
}
1354+
},
1355+
"401": {
1356+
"description": "Unauthorized: Invalid or missing Bearer token for k8s auth",
1357+
"content": {
1358+
"application/json": {
1359+
"schema": {
1360+
"$ref": "#/components/schemas/UnauthorizedResponse"
1361+
}
1362+
}
1363+
}
1364+
},
1365+
"403": {
1366+
"description": "User is not authorized",
1367+
"content": {
1368+
"application/json": {
1369+
"schema": {
1370+
"$ref": "#/components/schemas/ForbiddenResponse"
1371+
}
1372+
}
1373+
}
1374+
},
1375+
"500": {
1376+
"description": "Internal Server Error",
1377+
"detail": {
1378+
"response": "Unable to connect to Llama Stack",
1379+
"cause": "Connection error."
1380+
}
1381+
},
1382+
"422": {
1383+
"description": "Validation Error",
1384+
"content": {
1385+
"application/json": {
1386+
"schema": {
1387+
"$ref": "#/components/schemas/HTTPValidationError"
1388+
}
1389+
}
1390+
}
1391+
}
1392+
}
1393+
}
1394+
},
13091395
"/readiness": {
13101396
"get": {
13111397
"tags": [

‎docs/openapi.md‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -227,14 +227,10 @@ Returns:
227227

228228
> **Streaming Query Endpoint Handler**
229229
230-
Handle request to the /streaming_query endpoint.
230+
Handle request to the /streaming_query endpoint using Agent API.
231231

232-
This endpoint receives a query request, authenticates the user,
233-
selects the appropriate model and provider, and streams
234-
incremental response events from the Llama Stack backend to the
235-
client. Events include start, token updates, tool calls, turn
236-
completions, errors, and end-of-stream metadata. Optionally
237-
stores the conversation transcript if enabled in configuration.
232+
This is a wrapper around streaming_query_endpoint_handler_base that provides
233+
the Agent API specific retrieve_response and response generator functions.
238234

239235
Returns:
240236
StreamingResponse: An HTTP streaming response yielding
@@ -587,6 +583,42 @@ Returns:
587583
| 429 | The quota has been exceeded | [QuotaExceededResponse](#quotaexceededresponse) |
588584
| 500 | Internal Server Error | |
589585
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
586+
## POST `/v2/streaming_query`
587+
588+
> **Streaming Query Endpoint Handler V2**
589+
590+
Handle request to the /streaming_query endpoint using Responses API.
591+
592+
This is a wrapper around streaming_query_endpoint_handler_base that provides
593+
the Responses API specific retrieve_response and response generator functions.
594+
595+
Returns:
596+
StreamingResponse: An HTTP streaming response yielding
597+
SSE-formatted events for the query lifecycle.
598+
599+
Raises:
600+
HTTPException: Returns HTTP 500 if unable to connect to the
601+
Llama Stack server.
602+
603+
604+
605+
606+
607+
### 📦 Request Body
608+
609+
[QueryRequest](#queryrequest)
610+
611+
### ✅ Responses
612+
613+
| Status Code | Description | Component |
614+
|-------------|-------------|-----------|
615+
| 200 | Streaming response with Server-Sent Events | string
616+
string |
617+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
618+
| 401 | Unauthorized: Invalid or missing Bearer token for k8s auth | [UnauthorizedResponse](#unauthorizedresponse) |
619+
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
620+
| 500 | Internal Server Error | |
621+
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
590622
## GET `/readiness`
591623

592624
> **Readiness Probe Get Method**

‎docs/output.md‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -227,14 +227,10 @@ Returns:
227227

228228
> **Streaming Query Endpoint Handler**
229229
230-
Handle request to the /streaming_query endpoint.
230+
Handle request to the /streaming_query endpoint using Agent API.
231231

232-
This endpoint receives a query request, authenticates the user,
233-
selects the appropriate model and provider, and streams
234-
incremental response events from the Llama Stack backend to the
235-
client. Events include start, token updates, tool calls, turn
236-
completions, errors, and end-of-stream metadata. Optionally
237-
stores the conversation transcript if enabled in configuration.
232+
This is a wrapper around streaming_query_endpoint_handler_base that provides
233+
the Agent API specific retrieve_response and response generator functions.
238234

239235
Returns:
240236
StreamingResponse: An HTTP streaming response yielding
@@ -587,6 +583,42 @@ Returns:
587583
| 429 | The quota has been exceeded | [QuotaExceededResponse](#quotaexceededresponse) |
588584
| 500 | Internal Server Error | |
589585
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
586+
## POST `/v2/streaming_query`
587+
588+
> **Streaming Query Endpoint Handler V2**
589+
590+
Handle request to the /streaming_query endpoint using Responses API.
591+
592+
This is a wrapper around streaming_query_endpoint_handler_base that provides
593+
the Responses API specific retrieve_response and response generator functions.
594+
595+
Returns:
596+
StreamingResponse: An HTTP streaming response yielding
597+
SSE-formatted events for the query lifecycle.
598+
599+
Raises:
600+
HTTPException: Returns HTTP 500 if unable to connect to the
601+
Llama Stack server.
602+
603+
604+
605+
606+
607+
### 📦 Request Body
608+
609+
[QueryRequest](#queryrequest)
610+
611+
### ✅ Responses
612+
613+
| Status Code | Description | Component |
614+
|-------------|-------------|-----------|
615+
| 200 | Streaming response with Server-Sent Events | string
616+
string |
617+
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
618+
| 401 | Unauthorized: Invalid or missing Bearer token for k8s auth | [UnauthorizedResponse](#unauthorizedresponse) |
619+
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
620+
| 500 | Internal Server Error | |
621+
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
590622
## GET `/readiness`
591623

592624
> **Readiness Probe Get Method**

0 commit comments

Comments
 (0)