Skip to main content

​
Get All Documents

Source: HappyHabitat.API/Controllers/DocumentsController.cs:29
Retrieves all documents in the system. 
GET /api/Documents
Authorization: Bearer {token}
Authorization: Requires ADMIN_COMPANY or SYSTEM_ADMIN role Response: Array of DocumentDto objects

​
Get Documents by Community

Source: HappyHabitat.API/Controllers/DocumentsController.cs:39
Retrieves all documents for a specific community. 
GET /api/Documents/community/{communityId}
Authorization: Bearer {token}
Path Parameters
​
communityId
Guid
The community’s unique identifier. If omitted, returns documents with no community association.
Authorization: Requires ADMIN_COMPANY or SYSTEM_ADMIN role Response: Array of DocumentDto objects

​
Get Document by ID

Source: HappyHabitat.API/Controllers/DocumentsController.cs:49
Retrieves a specific document by its unique identifier. 
GET /api/Documents/{id}
Authorization: Bearer {token}
Path Parameters
​
id
Guid
required
The document’s unique identifier
Authorization: Requires ADMIN_COMPANY or SYSTEM_ADMIN role Response: DocumentDto object Status Codes
  • 200 OK: Document found
  • 404 Not Found: Document does not exist

​
Download Document

Source: HappyHabitat.API/Controllers/DocumentsController.cs:62
Downloads the file content of a document. Access is restricted to company admins of the document’s community or the user who uploaded it. 
GET /api/Documents/{id}/download
Authorization: Bearer {token}
Path Parameters
​
id
Guid
required
The document’s unique identifier
Authorization:
  • Requires ADMIN_COMPANY or SYSTEM_ADMIN role
  • User must be either:
    • A company admin for the document’s community
    • The user who uploaded the document
Response: Binary file with appropriate Content-Type header Status Codes
  • 200 OK: File download successful
  • 302 Found: Redirect to external URL or static file location
  • 400 Bad Request: Document has no file path
  • 401 Unauthorized: User not authenticated
  • 403 Forbidden: User lacks permission to download
  • 404 Not Found: Document does not exist
Behavior:
  • If the file exists on the filesystem, it’s served directly
  • If the file is not found but UrlDoc is an absolute URL (http/https), redirects to that URL
  • Otherwise, constructs and redirects to a static file URL

​
Create Document

Source: HappyHabitat.API/Controllers/DocumentsController.cs:128
Creates a new document record. The current authenticated user is automatically set as the uploader. 
POST /api/Documents
Authorization: Bearer {token}
Content-Type: application/json

{
  "communityId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "titulo": "Community Guidelines",
  "descripcion": "Updated guidelines for 2024",
  "fecha": "2024-03-15T00:00:00Z",
  "userCreated": "John Doe",
  "nombreDocumento": "guidelines_2024.pdf",
  "urlDoc": "uploads/documents/7c9e6679-7425-40de-944b-e07fc1f90ae7/general/general/guidelines_2024.pdf"
}
Request Body: CreateDocumentDto
​
communityId
Guid
The community to associate the document with
​
titulo
string
required
Document title (max 200 characters)
​
descripcion
string
Document description (max 2000 characters)
​
fecha
DateTime
required
Document date
​
userCreated
string
Name or identifier of the user who created it (max 200 characters)
​
nombreDocumento
string
required
Original file name (max 500 characters)
​
urlDoc
string
required
URL or relative path to the document file (max 1000 characters). Typically the relativePath from the upload response.
The userId field is automatically set from the authenticated user and should not be provided in the request.
Authorization: Requires ADMIN_COMPANY or SYSTEM_ADMIN role Response: DocumentDto object with 201 Created status Status Codes
  • 201 Created: Document successfully created
  • 400 Bad Request: Invalid request data or validation error

​
Update Document

Source: HappyHabitat.API/Controllers/DocumentsController.cs:148
Updates an existing document’s metadata. 
PUT /api/Documents/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "communityId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "titulo": "Community Guidelines - Revised",
  "descripcion": "Updated guidelines for 2024 with recent changes",
  "fecha": "2024-03-20T00:00:00Z",
  "userCreated": "John Doe",
  "nombreDocumento": "guidelines_2024_v2.pdf",
  "urlDoc": "uploads/documents/7c9e6679-7425-40de-944b-e07fc1f90ae7/general/general/guidelines_2024_v2.pdf"
}
Path Parameters
​
id
Guid
required
The document’s unique identifier
Request Body: UpdateDocumentDto
​
communityId
Guid
The community to associate the document with
​
titulo
string
required
Document title (max 200 characters)
​
descripcion
string
Document description (max 2000 characters)
​
fecha
DateTime
required
Document date
​
userCreated
string
Name or identifier of the user who created it (max 200 characters)
​
nombreDocumento
string
required
Original file name (max 500 characters)
​
urlDoc
string
required
URL or relative path to the document file (max 1000 characters)
Authorization: Requires ADMIN_COMPANY or SYSTEM_ADMIN role Response: DocumentDto object Status Codes
  • 200 OK: Document successfully updated
  • 400 Bad Request: Invalid request data or validation error
  • 404 Not Found: Document does not exist

​
Delete Document

Source: HappyHabitat.API/Controllers/DocumentsController.cs:168
Deletes a document record from the system. 
DELETE /api/Documents/{id}
Authorization: Bearer {token}
Path Parameters
​
id
Guid
required
The document’s unique identifier
Authorization: Requires ADMIN_COMPANY or SYSTEM_ADMIN role Response: No content Status Codes
  • 204 No Content: Document successfully deleted
  • 404 Not Found: Document does not exist
This endpoint only deletes the document record from the database. It does not delete the physical file from the filesystem.

​
Upload Document File

Source: HappyHabitat.API/Controllers/DocumentsController.cs:185
Uploads a file to the server filesystem with organized directory structure. 
POST /api/Documents/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [binary file data]
communityId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
residentId: 8d5f3e12-4a1b-4c2d-9e6f-7b8c9d0e1f2a
category: contracts
Form Parameters
​
file
IFormFile
required
The file to upload (max 20 MB)
​
communityId
Guid
required
The community’s unique identifier
​
residentId
Guid
The resident’s unique identifier. Defaults to “general” if not provided.
​
category
string
Document category (e.g., “contracts”, “reports”, “invoices”). Defaults to “general” if not provided. Only alphanumeric characters, hyphens, and underscores are allowed.
Authorization: Requires ADMIN_COMPANY or SYSTEM_ADMIN role Response: DocumentUploadResponse object
​
relativePath
string
The relative path where the file was saved. Use this value for Document.UrlDoc when creating the document record.
​
originalFileName
string
The original file name as sent by the client
​
fileSizeBytes
number
File size in bytes
Status Codes
  • 200 OK: File uploaded successfully
  • 400 Bad Request: No file provided, empty file, or invalid file name
  • 500 Internal Server Error: File system error during upload
File Organization: Files are stored in the following structure: 
uploads/documents/{communityId}/{category}/{residentId}/{fileName}
Example: 
uploads/documents/7c9e6679-7425-40de-944b-e07fc1f90ae7/contracts/8d5f3e12-4a1b-4c2d-9e6f-7b8c9d0e1f2a/lease_agreement.pdf
File Size Limit: 20 MB maximum
After uploading a file, use the returned relativePath as the urlDoc value when creating a document record via POST /api/Documents.

​
Upload Generic File

Source: HappyHabitat.API/Controllers/FileController.cs:24
Generic file upload endpoint that allows uploading to any specified relative path. This endpoint provides more flexibility than the Documents upload endpoint. 
POST /api/File/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [binary file data]
path: uploads/tickets/3fa85f64-5717-4562-b3fc-2c963f66afa6/screenshot.png
Form Parameters
​
file
IFormFile
required
The file to upload (max 20 MB)
​
path
string
required
Relative path where the file should be saved (e.g., “uploads/tickets/guid/image.jpg”). Path traversal is not allowed.
Authorization: Requires authentication (any authenticated user) Response: DocumentUploadResponse object
​
relativePath
string
The relative path where the file was saved
​
originalFileName
string
The original file name as sent by the client
​
fileSizeBytes
number
File size in bytes
Status Codes
  • 200 OK: File uploaded successfully
  • 400 Bad Request: No file provided, empty file, missing path, or invalid path (path traversal detected)
  • 500 Internal Server Error: File system error during upload
Security:
  • Path traversal attempts are blocked
  • The resolved path must be under the application’s content root path
  • Paths are normalized to prevent directory traversal attacks
File Size Limit: 20 MB maximum
This endpoint requires a valid relative path. Ensure the path does not attempt directory traversal (e.g., ”../” sequences).

​
Data Models

​
DocumentDto

Response model for document operations. 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "communityId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "communityName": "Sunset Valley Community",
  "userId": "8d5f3e12-4a1b-4c2d-9e6f-7b8c9d0e1f2a",
  "titulo": "Community Guidelines",
  "descripcion": "Updated guidelines for 2024",
  "fecha": "2024-03-15T00:00:00Z",
  "userCreated": "John Doe",
  "nombreDocumento": "guidelines_2024.pdf",
  "urlDoc": "uploads/documents/7c9e6679-7425-40de-944b-e07fc1f90ae7/general/general/guidelines_2024.pdf",
  "createdAt": "2024-03-15T10:30:00Z"
}

​
CreateDocumentDto

Request model for creating documents. 
{
  "communityId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "titulo": "Community Guidelines",
  "descripcion": "Updated guidelines for 2024",
  "fecha": "2024-03-15T00:00:00Z",
  "userCreated": "John Doe",
  "nombreDocumento": "guidelines_2024.pdf",
  "urlDoc": "uploads/documents/7c9e6679-7425-40de-944b-e07fc1f90ae7/general/general/guidelines_2024.pdf"
}
Do not include userId in the request. It is automatically set from the authenticated user.

​
UpdateDocumentDto

Request model for updating documents. 
{
  "communityId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "titulo": "Community Guidelines - Revised",
  "descripcion": "Updated guidelines for 2024 with recent changes",
  "fecha": "2024-03-20T00:00:00Z",
  "userCreated": "John Doe",
  "nombreDocumento": "guidelines_2024_v2.pdf",
  "urlDoc": "uploads/documents/7c9e6679-7425-40de-944b-e07fc1f90ae7/general/general/guidelines_2024_v2.pdf"
}

​
DocumentUploadResponse

Response model for file upload operations. 
{
  "relativePath": "uploads/documents/7c9e6679-7425-40de-944b-e07fc1f90ae7/contracts/8d5f3e12-4a1b-4c2d-9e6f-7b8c9d0e1f2a/lease_agreement.pdf",
  "originalFileName": "lease_agreement.pdf",
  "fileSizeBytes": 524288
}

Build docs developers (and LLMs) love

Get started for freeTalk to us