Skip to main content

Projects API

Manage real-estate projects. All endpoints are JWT cookie authenticated and require one of the roles: admin, sales, finance, or agent (router-level authorization).

Base URL: /api/projects

Authentication​

This API uses an HTTP-only cookie named token (JWT). Include the cookie returned from a successful login in subsequent requests.

Roles allowed on this router: admin, sales, finance, agent.

Data Model​

A Project returned by the endpoints has the following shape (fields may vary slightly by endpoint):

{
  "id": 1,
  "name": "Downtown Heights",
  "description": "Mixed-use development",
  "isActive": true,
  "createdBy": 12,
  "developerId": 3,
  "developerName": "Acme Developers",
  "createdAt": "2024-07-01T10:15:00.000Z",
  "updatedAt": "2024-07-10T08:01:00.000Z",
  "company": 5
}

Create/Update payload​

{
  "name": "Downtown Heights",          // required, string
  "company": 5,                         // required, number (company id)
  "description": "Mixed-use dev.",     // optional, string
  "developerId": 3                      // required for create, number (developer id)
}

Endpoints​

GET / — List all projects​

Returns all projects the caller is authorized to view. Includes developer name.

Permissions: admin | sales | finance | agent

Response — 200

[
  {
    "id": 1,
    "name": "Downtown Heights",
    "description": "Mixed-use development",
    "isActive": true,
    "createdBy": 12,
    "developerId": 3,
    "developerName": "Acme Developers",
    "createdAt": "2024-07-01T10:15:00.000Z",
    "updatedAt": "2024-07-10T08:01:00.000Z",
    "company": 5
  }
]

Errors

  • 500 — {"message":"Error retrieving projects"}

cURL

curl -sS --cookie "token=<JWT>" \
  https://<host>/api/projects

GET /single/:id — Get a project by id​

Returns a single project by its id with joined developer name.

Path params

  • id (number) — Project id

Response — 200

[
  {
    "id": 1,
    "name": "Downtown Heights",
    "description": "Mixed-use development",
    "isActive": true,
    "createdBy": 12,
    "developerId": 3,
    "developerName": "Acme Developers",
    "createdAt": "2024-07-01T10:15:00.000Z",
    "updatedAt": "2024-07-10T08:01:00.000Z",
    "company": 5
  }
]

Note: The implementation returns an array with one element (due to SQL builder usage). Select index 0 for the object.

Errors

  • 500 — {"message":"Error retrieving project"}

cURL

curl -sS --cookie "token=<JWT>" \
  https://<host>/api/projects/single/1

GET /:companyId — List projects by company​

Returns all projects that belong to a given company id.

Path params

  • companyId (number) — Company id

Response — 200

[
  {
    "id": 2,
    "name": "Harbor Views",
    "description": "Waterfront living",
    "isActive": true,
    "createdBy": 18,
    "developerId": 4,
    "developerName": "Harbor DevCo",
    "createdAt": "2024-03-12T12:00:00.000Z",
    "updatedAt": "2024-05-01T09:30:00.000Z",
    "company": 7
  }
]

Errors

  • 500 — {"message":"Error retrieving projects"}

cURL

curl -sS --cookie "token=<JWT>" \
  https://<host>/api/projects/7

POST / — Create a project​

Creates a new project. createdBy is taken from the authenticated user. The developerId must refer to an existing developer record.

Body

{
  "name": "Downtown Heights",
  "company": 5,
  "description": "Mixed-use development",
  "developerId": 3
}

Response — 201

{"message":"Project created successfully"}

Errors

  • 404 — {"message":"Developer not found"}
  • 500 — {"message":"Error creating project"}

cURL

curl -sS -X POST --cookie "token=<JWT>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Downtown Heights",
        "company": 5,
        "description": "Mixed-use development",
        "developerId": 3
      }' \
  https://<host>/api/projects

PUT /:id — Update a project​

Updates a project’s basic fields.

Path params

  • id (number) — Project id

Body (any of)

{
  "name": "Downtown Heights Phase 2",
  "company": 5,
  "description": "Expanded scope"
}

Response — 200

{"message":"Project updated successfully"}

Errors

  • 500 — {"message":"Error updating project"}

cURL

curl -sS -X PUT --cookie "token=<JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Downtown Heights Phase 2","company":5,"description":"Expanded scope"}' \
  https://<host>/api/projects/1

DELETE /:id — Delete a project​

Deletes the project by id.

Path params

  • id (number) — Project id

Response — 200

{"message":"Project deleted successfully"}

Errors

  • 500 — {"message":"Error deleting project"}

cURL

curl -sS -X DELETE --cookie "token=<JWT>" \
  https://<host>/api/projects/1

Notes & Behavior​

  • All endpoints on this router require roles: admin, sales, finance, or agent.
  • Responses are plain JSON; there is no pagination or filtering on the list endpoints in the current implementation.
  • createdBy is set server-side from the authenticated user on create.
  • Timestamps are ISO strings.

Status Codes Summary​

  • 200 OK – Successful read/update/delete
  • 201 Created – Successful create
  • 404 Not Found – Related entity not found (e.g., developer)
  • 500 Internal Server Error – Unhandled server/database error