The Bloom Housing API is a REST API built with NestJS and backed by a PostgreSQL database via Prisma . All request and response bodies use JSON.
Base URL Environment Base URL Local development http://localhost:3100Production Your deployed API host
Interactive API docs OpenAPI/Swagger documentation is automatically generated and served at /api relative to the API base URL. In local development, open http://localhost:3100/api in a browser to browse all endpoints interactively and send test requests.
All endpoints accept and return application/json. Include the header on write operations:
Content-Type : application/json
Endpoints that return lists accept the following query parameters:
Parameter Type Description pagenumber Page number (1-indexed) limitnumber Number of results per page
API key authentication Certain endpoints require an API pass-key in addition to (or instead of) a user JWT. Pass the key in the API_PASS_KEY request header. The expected value is set via the API_PASS_KEY environment variable on the server.
API_PASS_KEY : your-api-key
Endpoints protected by the API key guard will return 401 Unauthorized if the header is missing or incorrect.
Rate limiting The API applies rate limiting controlled by two environment variables:
Variable Description THROTTLE_TTLTime window in milliseconds THROTTLE_LIMITMaximum requests allowed per window
When the limit is exceeded, the API returns 429 Too Many Requests.
CORS Cross-origin requests are controlled by:
Variable Description CORS_ORIGINSComma-separated list of allowed origins CORS_REGEXRegular expression pattern for allowed origins
Available endpoints
Listings /listingsBrowse and manage housing listings. Publicly readable. Create, update, and delete require partner or admin role.
Applications /applicationsSubmit and manage applications to listings. Anonymous users can submit. Viewing and managing requires authentication.
Users /userCreate and manage user accounts. Profile updates are scoped to the authenticated user. Admin operations require elevated roles.
Authentication /authLog in, log out, request MFA codes, and refresh tokens. See the Authentication page for details.
Jurisdictions /jurisdictionsRead and manage jurisdiction configuration. Publicly readable. Write operations require admin.
Lottery /lotteryRun and manage lottery operations for listings.
AMI Charts /amiChartsArea median income chart data used for unit eligibility calculations.
Multiselect Questions /multiselectQuestionsPreferences and programs attached to listings and applications.
Unit Types /unitTypesReference data for unit types (studio, 1BR, 2BR, etc.).
Unit Rent Types /unitRentTypesReference data for rent calculation types.
Reserved Community Types /reservedCommunityTypesTypes for listings reserved for specific communities (veterans, seniors, etc.).
Assets /assetsUpload and retrieve file and image assets attached to listings.
Feature Flags /featureFlagsRead and manage feature flags that control platform behavior per jurisdiction.
Map Layers /mapLayersGeographic map layer data for listing maps.
Agencies /agencyAgency data associated with listings and users.
Properties /propertiesProperty records grouping multiple listings under a single building. Requires enableProperties feature flag.
Application Flagged Sets /applicationFlaggedSetsDuplicate application detection and resolution.