Skip to content

schemas

Here's the reference for all response models and types provided by the schemas module.

You can import them directly from fastapi_toolsets.schemas:

from fastapi_toolsets.schemas import (
    PydanticBase,
    ResponseStatus,
    ApiError,
    BaseResponse,
    Response,
    ErrorResponse,
    OffsetPagination,
    CursorPagination,
    PaginationType,
    PaginatedResponse,
    OffsetPaginatedResponse,
    CursorPaginatedResponse,
)

fastapi_toolsets.schemas.PydanticBase

Bases: BaseModel

Base class for all Pydantic models with common configuration.

fastapi_toolsets.schemas.ResponseStatus

Bases: str, Enum

Standard API response status.

fastapi_toolsets.schemas.ApiError

Bases: PydanticBase

Structured API error definition.

Used to define standard error responses with consistent format.

Attributes:

Name Type Description
code int

HTTP status code
msg str

Short error message
desc str

Detailed error description
err_code str

Application-specific error code (e.g., "AUTH-401")

fastapi_toolsets.schemas.BaseResponse

Bases: PydanticBase

Base response structure for all API responses.

Attributes:

Name Type Description
status ResponseStatus

SUCCESS or FAIL
message str

Human-readable message
error_code str | None

Error code if status is FAIL, None otherwise

fastapi_toolsets.schemas.Response

Bases: BaseResponse, Generic[DataT]

Generic API response with data payload.

Example 
Response[UserRead](data=user, message="User retrieved")

fastapi_toolsets.schemas.ErrorResponse

Bases: BaseResponse

Error response with additional description field.

Used for error responses that need more context.

fastapi_toolsets.schemas.OffsetPagination

Bases: PydanticBase

Pagination metadata for offset-based list responses.

Attributes:

Name Type Description
total_count int | None

Total number of items across all pages. None when include_total=False.
items_per_page int

Number of items per page
page int

Current page number (1-indexed)
has_more bool

Whether there are more pages
pages int | None

Total number of pages

pages property

Total number of pages, or None when total_count is unknown.

fastapi_toolsets.schemas.CursorPagination

Bases: PydanticBase

Pagination metadata for cursor-based list responses.

Attributes:

Name Type Description
next_cursor str | None

Encoded cursor for the next page, or None on the last page.
prev_cursor str | None

Encoded cursor for the previous page, or None on the first page.
items_per_page int

Number of items requested per page.
has_more bool

Whether there is at least one more page after this one.

fastapi_toolsets.schemas.PaginationType

Bases: str, Enum

Pagination strategy selector for :meth:.AsyncCrud.paginate.

fastapi_toolsets.schemas.PaginatedResponse

Bases: BaseResponse, Generic[DataT]

Paginated API response for list endpoints.

Base class and return type for endpoints that support both pagination strategies. Use :class:OffsetPaginatedResponse or :class:CursorPaginatedResponse when the strategy is fixed.

When used as PaginatedResponse[T] in a return annotation, subscripting returns Annotated[Union[CursorPaginatedResponse[T], OffsetPaginatedResponse[T]], Field(discriminator="pagination_type")] so FastAPI emits a proper oneOf + discriminator in the OpenAPI schema.

fastapi_toolsets.schemas.OffsetPaginatedResponse

Bases: PaginatedResponse[DataT]

Paginated response with typed offset-based pagination metadata.

The pagination_type field is always "offset" and acts as a discriminator, allowing frontend clients to narrow the union type returned by a unified paginate() endpoint.

fastapi_toolsets.schemas.CursorPaginatedResponse

Bases: PaginatedResponse[DataT]

Paginated response with typed cursor-based pagination metadata.

The pagination_type field is always "cursor" and acts as a discriminator, allowing frontend clients to narrow the union type returned by a unified paginate() endpoint.