Vorte

Response Envelope

Vorte wraps every API response in a consistent JSON envelope. This makes it easy for clients to parse responses uniformly and handle errors predictably.

Standard Envelope

Every response follows this structure:

data.json
json
Copied!
1{
2 "success": true,
3 "data": { ... },
4 "meta": {
5 "request_id": "req_abc123",
6 "timestamp": "2026-05-23T10:30:00Z",
7 "version": "1.0.0"
8 },
9 "errors": []
10}

For error responses:

data.json
json
Copied!
1{
2 "success": false,
3 "data": null,
4 "meta": {
5 "request_id": "req_def456",
6 "timestamp": "2026-05-23T10:30:01Z",
7 "version": "1.0.0"
8 },
9 "errors": [
10 {
11 "code": "VALIDATION_ERROR",
12 "message": "Field 'email' is required",
13 "field": "email"
14 }
15 ]
16}

Response Helpers

Vorte provides helper functions that construct properly formatted envelopes for common response patterns.

success_response

get_user.py
python
Copied!
1from vorte.response import success_response
2
3@router.get("/users/{user_id}")
4async def get_user(user_id: int):
5 user = await db.get_user(user_id)
6 return success_response(
7 data=user,
8 message="User retrieved successfully",
9 )

Output:

data.json
json
Copied!
1{
2 "success": true,
3 "data": {"id": 1, "name": "Alice", "email": "alice@example.com"},
4 "message": "User retrieved successfully",
5 "meta": {"request_id": "req_abc123", "timestamp": "2026-05-23T10:30:00Z"}
6}

error_response

get_user.py
python
Copied!
1from vorte.response import error_response
2
3@router.get("/users/{user_id}")
4async def get_user(user_id: int):
5 user = await db.get_user(user_id)
6 if not user:
7 return error_response(
8 code="NOT_FOUND",
9 message=f"User {user_id} not found",
10 status_code=404,
11 )
12 return success_response(data=user)

paginated_response

list_users.py
python
Copied!
1from vorte.response import paginated_response
2
3@router.get("/users")
4async def list_users(page: int = 1, per_page: int = 20):
5 result = await db.paginate("users", page=page, per_page=per_page)
6 return paginated_response(
7 items=result.items,
8 total=result.total,
9 page=page,
10 per_page=per_page,
11 )

Output:

data.json
json
Copied!
1{
2 "success": true,
3 "data": [
4 {"id": 1, "name": "Alice"},
5 {"id": 2, "name": "Bob"}
6 ],
7 "pagination": {
8 "total": 100,
9 "page": 1,
10 "per_page": 20,
11 "total_pages": 5,
12 "has_next": true,
13 "has_prev": false
14 },
15 "meta": {"request_id": "req_ghi789", "timestamp": "2026-05-23T10:30:02Z"}
16}

ai_response

chat.py
python
Copied!
1from vorte.response import ai_response
2
3@router.post("/chat")
4async def chat(prompt: str):
5 result = await ai.complete(prompt)
6 return ai_response(
7 content=result.text,
8 model=result.model,
9 tokens=result.usage.total_tokens,
10 latency_ms=result.latency,
11 )

Output:

data.json
json
Copied!
1{
2 "success": true,
3 "data": {
4 "content": "The answer is 42.",
5 "model": "gpt-4o",
6 "usage": {
7 "prompt_tokens": 10,
8 "completion_tokens": 8,
9 "total_tokens": 18
10 },
11 "latency_ms": 450
12 },
13 "meta": {"request_id": "req_jkl012", "timestamp": "2026-05-23T10:30:03Z"}
14}

Streaming Responses

Vorte provides two streaming response types for real-time data delivery, commonly used with AI completions and live feeds.

VorteSSEResponse

Server-Sent Events for unidirectional streaming from server to client. Ideal for AI token streaming.

chat_stream.py
python
Copied!
1from vorte.response import VorteSSEResponse
2
3@router.post("/chat/stream")
4async def chat_stream(prompt: str):
5 async def generate():
6 async for token in ai.stream(prompt):
7 yield {"token": token, "done": False}
8 yield {"token": "", "done": True}
9
10 return VorteSSEResponse(generate())

VorteStreamResponse

A generic streaming response for chunked transfer encoding. Useful for large file downloads or binary streams.

export_report.py
python
Copied!
1from vorte.response import VorteStreamResponse
2
3@router.get("/export/{report_id}")
4async def export_report(report_id: str):
5 async def generate_chunks():
6 chunk_size = 8192
7 async for chunk in storage.stream(f"reports/{report_id}.csv"):
8 yield chunk
9
10 return VorteStreamResponse(
11 generate_chunks(),
12 content_type="text/csv",
13 headers={
14 "Content-Disposition": f"attachment; filename={report_id}.csv"
15 },
16 )

Custom Envelopes

Override the default envelope format for specific routes or the entire application.

example.py
python
Copied!
1from vorte.response import success_response, EnvelopeConfig
2
3app = Vorte(
4 auto_load=True,
5 config={
6 "response": {
7 "envelope": {
8 "enabled": True,
9 "include_meta": True,
10 "include_request_id": True,
11 "include_timestamp": True,
12 "include_version": False,
13 }
14 }
15 },
16)
Stay in the loop

Get Vorte release notes, module guides, and developer deep-dives. No spam — unsubscribe anytime.