API Request and Response Schemas¶

This reference documents the request and response models defined in the WhiteLotusAI REST API gateway. It covers authentication, profile management, sessions, chat, and retrieval-augmented generation (RAG), including field constraints, defaults, and outstanding contract-verification work.

Documentation status

This page is a source-derived schema reference. Model definitions establish expected data shapes, but they do not prove that every endpoint returns the declared response model or that every contract has been verified at runtime.

At a glance¶

Request models

Field types, required values, defaults, and validation constraints for incoming requests.
Response models

Documented response structures for authentication, sessions, chat, and RAG.
Validation behaviour

Shared model configuration, password validation, and file-ingestion constraints.
Contract verification

Open findings covering route differences, response bodies, enum values, and runtime validation.

1. Scope and source layout¶

The primary gateway schema definitions are located in rest_api/package/app/schemas/.

Schema module	Responsibility
`common.py`	Shared model configuration and base response schemas
`user.py`	Registration, login, tokens, user profiles, and password changes
`session.py`	Session metadata, messages, and conversation history
`chat.py`	Chat request and response models
`rag.py`	Document ingestion, search, search results, and document metadata
`__init__.py`	Schema package exports; verify the current source for the exported models

This page does not claim to cover every request and response model in the integrations package or internal services.

Schema interaction overview¶

The following diagram illustrates the relationship between client requests, gateway validation, and service handling. It is a conceptual view, not proof that every endpoint follows an identical execution path.

flowchart TD
    CLIENT["Client request"]
    GATEWAY["REST API gateway"]
    VALIDATE["Request schema validation"]
    HANDLER["Route handler"]
    SERVICE["Downstream service"]
    RESPONSE["Response serialization"]
    ERROR["Validation or handler error"]

    CLIENT --> GATEWAY
    GATEWAY --> VALIDATE
    VALIDATE -->|Valid input| HANDLER
    VALIDATE -->|Invalid input| ERROR
    HANDLER --> SERVICE
    SERVICE --> RESPONSE

    classDef client fill:#E8F0FE,stroke:#5277B8,color:#172B4D
    classDef gateway fill:#EDE7F6,stroke:#8064A2,color:#35234A
    classDef validation fill:#DDF4EA,stroke:#38866A,color:#153D30
    classDef service fill:#FFF0D8,stroke:#B98132,color:#56390E
    classDef error fill:#FCE8E6,stroke:#C65D54,color:#632B26

    class CLIENT client
    class GATEWAY gateway
    class VALIDATE validation
    class HANDLER,SERVICE service
    class RESPONSE validation
    class ERROR error

2. Shared schema behaviour¶

Source: rest_api/package/app/schemas/common.py

The shared BaseModel configures the following behaviour:

Behaviour	Description
String whitespace	Leading and trailing whitespace is stripped from string values.
Extra fields	Unrecognised fields are ignored.
Attribute-based construction	Models support construction from object attributes.
Datetime serialization	An ISO-formatted JSON encoder is configured for datetime values.

These settings describe the shared model configuration. Confirm inheritance and any model-specific overrides before assuming that every schema behaves identically.

2.1 Base response schema¶

Model: BaseResponseSchema

Field	Type	Required
`message`	Optional string	No
`errors`	Optional dictionary	No
`special_code`	Optional integer	No
`warning`	Optional string	No

2.2 Validation error schema¶

Model: ValidationErrorResponseSchema

Field	Type	Behaviour
`message`	String	Defaults to `"Validation error"`
`errors`	Dictionary	Carries validation error details

Response consistency

The existence of a shared response schema does not establish that every route uses it. Inspect the route's exception handling, response declarations, and actual returned body before treating this as a universal error-response contract.

3. Authentication schemas¶

Source: rest_api/package/app/schemas/user.py

3.1 Registration request¶

Model: RegisterRequestSchema

Field	Type	Constraints
`email`	Email address	Must satisfy email validation.
`display_name`	String	2–100 characters.
`password`	String	Must satisfy `PasswordField` validation.

The password validator requires at least eight characters, including all of the following:

At least one digit.
At least one uppercase letter.
At least one lowercase letter.
At least one special character from the configured allowed set.

The configured special-character set should be checked in the current implementation rather than inferred from an example password.

Model: LoginRequestSchema

Field	Type	Constraints
`email`	Email address	Must satisfy email validation.
`password`	String	1–128 characters.

3.3 Refresh and logout request¶

Model: RefreshRequestSchema

Field	Type	Constraints
`refresh_token`	String	No additional field-level length constraint is declared.

The inspected source uses this model for both refresh and logout handlers.

3.4 Token response¶

Model: TokenResponseSchema

Field	Type	Required
`access_token`	String	Yes
`refresh_token`	String	Yes
`token_type`	String	No; defaults to `bearer`

3.5 User response¶

Model: UserResponseSchema

Field	Type	Required
`user_id`	String	Yes
`email`	String	Yes
`display_name`	String	Yes
`role`	String	Yes
`is_active`	Boolean	Yes
`avatar_url`	Optional string	No
`created_at`	Optional string	No
`updated_at`	Optional string	No

Models: LoginResponseSchema and RegisterResponseSchema

Both models contain:

Field	Type	Required
`access_token`	String	Required
`refresh_token`	String	Yes
`token_type`	String	No; defaults to `bearer`
`user`	`UserResponseSchema`	Yes

The registration route declares HTTP status 201. The login handler sets its response status from the downstream user-service response.

Verify the effective contract

Check the actual status codes and response bodies for successful and unsuccessful requests. A typed success model alone does not describe all possible responses.

4. Profile schemas¶

Source: rest_api/package/app/schemas/user.py

4.1 Profile update¶

Model: UpdateProfileRequestSchema

Field	Type	Constraints
`display_name`	Optional string	2–100 characters when supplied.
`avatar_url`	Optional string	Maximum 500 characters when supplied.

The handler uses model_dump(exclude_unset=True). Consequently, omitted fields are not forwarded as explicit updates by that serialization step.

4.2 Password change¶

Model: ChangePasswordRequestSchema

Field	Type	Constraints
`current_password`	String	1–128 characters.
`new_password`	String	Must satisfy `PasswordField` validation.

The new password uses the shared password validation rules described in Section 3.

5. Session schemas¶

Source: rest_api/package/app/schemas/session.py

5.1 Session rename¶

Model: SessionRenameSchema

Field	Type	Required
`title`	String	Yes

No field-level length constraint for title is declared in the inspected model.

5.2 Session response¶

Model: SessionResponseSchema

Field	Type	Required
`session_id`	String	Yes
`title`	Optional string	No; defaults to `New chat`
`created_at`	Optional datetime	No
`updated_at`	Optional datetime	No

5.3 Message schema¶

Model: MessageSchema

Field	Type	Default or constraint
`role`	Literal string	`user` or `assistant`
`type`	Literal string	`text`, `action`, or `document_selector`; defaults to `text`
`content`	String	Defaults to an empty string.
`data`	Dictionary	Defaults to an empty dictionary.

5.4 History response¶

Model: HistoryResponseSchema

Field	Type	Required
`session_id`	String	Yes
`messages`	List of `MessageSchema`	No; defaults to an empty list.

6. Chat schemas¶

Source: rest_api/package/app/schemas/chat.py

6.1 Chat request¶

Model: ChatRequestSchema

Field	Type	Constraints
`session_id`	String	1–64 characters.
`message`	String	1–4,000 characters.
`display_message`	Optional string	Maximum 4,000 characters when supplied.

The request contains session_id and message. The optional display_message field can represent display text separately from the main message.

6.2 Chat response¶

Model: ChatResponseSchema

Field	Type	Required
`response`	String	Yes
`session_id`	String	Yes

Streaming route requires verification

The schema documentation references /api/chat/stream, but the inspected gateway chat router is empty and streaming is handled separately through proxy routing. Confirm the effective public URL, event format, and response payload before treating ChatResponseSchema as the contract for the live streaming endpoint.

7. RAG schemas¶

Source: rest_api/package/app/schemas/rag.py

7.1 Text ingestion request¶

Model: IngestRequestSchema

Field	Type	Constraints
`text`	String	Minimum 10 characters.
`source`	String	1–255 characters.

7.2 Search request¶

Model: SearchRequestSchema

Field	Type	Constraints
`query`	String	1–4,000 characters.
`top_k`	Integer	1–10; defaults to `3`.

7.3 Search result¶

Model: SearchResultSchema

Field	Type	Required
`chunk_id`	String	Yes
`source`	String	Yes
`content`	String	Yes
`score`	Float	Yes
`page_number`	Optional integer	No
`doc_id`	Optional string	No
`metadata`	Dictionary	No; defaults to an empty dictionary.

7.4 Search response¶

Model: SearchResponseSchema

Field	Type	Required
`query`	String	Yes
`results`	List of `SearchResultSchema`	No; defaults to an empty list.

7.5 Document information¶

Model: DocumentInfoSchema

Field	Type	Required
`doc_id`	String	Yes
`source`	String	Yes
`chunk_count`	Integer	Yes
`status`	`DocumentStatus` enum	Yes
`file_type`	Optional string	No
`mime_type`	Optional string	No
`file_size`	Optional integer	No
`user_id`	Optional string	No
`tenant_id`	Optional string	No
`company_visible`	Boolean	No; defaults to `false`.
`created_at`	Optional string	No
`updated_at`	Optional string	No

The allowed status values are defined by the shared DocumentStatus enum. Consult the enum's current source for the exact values.

7.6 Ingestion response¶

Model: IngestResponseSchema

Field	Type	Required
`doc_id`	String	Yes
`source`	String	Yes
`chunk_count`	Integer	Yes
`status`	`DocumentStatus` enum	Yes

This model is documented for text and file ingestion responses. Error paths may return different response shapes.

8. File ingestion constraints¶

Route source: rest_api/package/app/api/rag.py

The file-ingestion handler:

Accepts a multipart file upload.
Accepts an optional source form field.
Uses the original filename as the source label when no source is supplied.
Validates that the source label is non-empty and no longer than 255 characters.
Checks the filename extension against SUPPORTED_EXTENSIONS.
Applies a configured maximum file size through MAX_DOCUMENT_SIZE_MB.
Attempts to extract text from the uploaded file.

The inspected source includes error responses for unsupported file types, oversized files, unreadable files, empty extracted text, and duplicate documents.

Do not assume deployment limits

Verify the actual SUPPORTED_EXTENSIONS values and configured MAX_DOCUMENT_SIZE_MB in the current source and deployment environment before publishing fixed values.

File-ingestion flow¶

flowchart TD
    UPLOAD["Multipart file upload"]
    SOURCE["Resolve source label"]
    EXT{"Extension supported?"}
    SIZE{"Within size limit?"}
    EXTRACT["Extract document text"]
    CONTENT{"Text extracted?"}
    DUPLICATE{"Duplicate document?"}
    ACCEPT["Continue ingestion"]
    REJECT["Return an error response"]

    UPLOAD --> SOURCE
    SOURCE --> EXT
    EXT -->|Yes| SIZE
    EXT -->|No| REJECT
    SIZE -->|Yes| EXTRACT
    SIZE -->|No| REJECT
    EXTRACT --> CONTENT
    CONTENT -->|Yes| DUPLICATE
    CONTENT -->|No| REJECT
    DUPLICATE -->|No| ACCEPT
    DUPLICATE -->|Yes| REJECT

    classDef input fill:#E8F0FE,stroke:#5277B8,color:#172B4D
    classDef check fill:#FFF0D8,stroke:#B98132,color:#56390E
    classDef success fill:#DDF4EA,stroke:#38866A,color:#153D30
    classDef failure fill:#FCE8E6,stroke:#C65D54,color:#632B26

    class UPLOAD,SOURCE input
    class EXT,SIZE,CONTENT,DUPLICATE check
    class ACCEPT success
    class REJECT failure

The diagram summarises the documented checks; verify the exact order and all failure paths against the current handler.

9. Example payloads¶

The following payloads are illustrative and contain no production credentials or private user data.

RegistrationLoginRAG ingestionRAG search

{
  "email": "user@example.com",
  "display_name": "Example User",
  "password": "<your_password>"
}

{
  "email": "user@example.com",
  "password": "<your_password>"
}

{
  "text": "Example document content with sufficient length.",
  "source": "example-document.txt"
}

{
  "query": "What information is available in the example document?",
  "top_k": 3
}

Credential handling

Never include real passwords, access tokens, refresh tokens, private user content, or production data in documentation examples. Use synthetic values and non-production test accounts.

10. Open schema and contract findings¶

The following items remain verification tasks. They should be closed only when supported by source inspection, generated schema output, or test evidence.

ID	Finding	Required verification
`SCHEMA-01`	The schema inventory does not cover all integration endpoints.	Inspect integration request models and provider handlers.
`SCHEMA-02`	Some handlers return error dictionaries despite declaring typed success models.	Verify response bodies and status codes for success and failure paths.
`SCHEMA-03`	The chat schema's documented route differs from the streaming routing arrangement.	Confirm the public URL and actual streaming contract.
`SCHEMA-04`	The exact `DocumentStatus` values are not listed here.	Inspect the shared enum definition.
`SCHEMA-05`	Runtime validation and generated OpenAPI output have not been tested for every route.	Compare generated schemas with representative valid and invalid requests.
`SCHEMA-06`	Shared model configuration ignores extra fields.	Confirm that this behaviour is intended for every request model and document exceptions.

Recommended verification order

Resolve the public route and streaming contract.
Compare route response declarations with actual returned payloads.
Document the exact enum values and file-upload limits.
Generate OpenAPI output and exercise valid and invalid requests.
Expand the inventory to cover integration endpoints.

These findings identify documentation and verification gaps. They do not imply that a particular runtime failure has been reproduced.

11. Source references¶

The following source files are the primary references for this page:

rest_api/package/app/schemas/common.py
rest_api/package/app/schemas/user.py
rest_api/package/app/schemas/session.py
rest_api/package/app/schemas/chat.py
rest_api/package/app/schemas/rag.py
rest_api/package/app/schemas/__init__.py
rest_api/package/app/api/auth.py
rest_api/package/app/api/profile.py
rest_api/package/app/api/session.py
rest_api/package/app/api/rag.py

12. Maintenance and change control¶

Update this page whenever a request model, response model, validation rule, or route contract changes.

Before marking a schema change as verified:

Confirm field names, types, required status, defaults, and constraints.
Check model inheritance and configuration overrides.
Compare response declarations with actual handler behaviour.
Verify HTTP status codes and error response bodies.
Regenerate or inspect OpenAPI output.
Run representative valid and invalid request tests.
Record any remaining discrepancies as explicit findings.

Documentation principle

Keep source-derived facts, observed runtime behaviour, and proposed improvements clearly separated. A model declaration is evidence of an intended data shape, not a guarantee of a complete or verified API contract.