santhoshj/headroom
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): regenerate Scribe API documentation

Browse Source 
Update auto-generated API documentation:
- New endpoints: ProjectMonthPlan, Reports, Roles
- Updated endpoint docs for Allocations and Projects
- Regenerated Scribe index with new endpoints

Documentation now reflects enhanced-allocation features.
This commit is contained in:
Santhosh Janardhanan
2026-03-08 18:23:11 -04:00
parent dd8055f6b7
commit b9775f2f5a
12 changed files with 6446 additions and 2590 deletions
Download Patch File Download Diff File Expand all files Collapse all files

642
backend/.scribe/endpoints.cache/02.yaml
View File

@@ -1,117 +1,25 @@
## Autogenerated by Scribe. DO NOT MODIFY.
name: Projects
name: 'Team Members'
description: |-
Endpoints for managing projects.
Endpoints for managing team members.
endpoints:
-
custom: []
httpMethods:
- GET
uri: api/projects/types
uri: api/team-members
metadata:
custom: []
groupName: Projects
groupName: 'Team Members'
groupDescription: |-
Endpoints for managing projects.
Endpoints for managing team members.
subgroup: ''
subgroupDescription: ''
title: 'Get all project types'
description: ''
authenticated: true
deprecated: false
headers:
Content-Type: application/json
Accept: application/json
urlParameters: []
cleanUrlParameters: []
queryParameters: []
cleanQueryParameters: []
bodyParameters: []
cleanBodyParameters: []
fileParameters: []
responses:
-
custom: []
status: 200
content: |-
{
"data": [
{"id": 1, "name": "Project"},
{"id": 2, "name": "Support"},
{"id": 3, "name": "Engagement"}
]
}
headers: []
description: ''
responseFields: []
auth: []
controller: null
method: null
route: null
-
custom: []
httpMethods:
- GET
uri: api/projects/statuses
metadata:
custom: []
groupName: Projects
groupDescription: |-
Endpoints for managing projects.
subgroup: ''
subgroupDescription: ''
title: 'Get all project statuses'
description: ''
authenticated: true
deprecated: false
headers:
Content-Type: application/json
Accept: application/json
urlParameters: []
cleanUrlParameters: []
queryParameters: []
cleanQueryParameters: []
bodyParameters: []
cleanBodyParameters: []
fileParameters: []
responses:
-
custom: []
status: 200
content: |-
{
"data": [
{"id": 1, "name": "Pre-sales", "order": 1},
{"id": 2, "name": "SOW Approval", "order": 2},
{"id": 3, "name": "Gathering Estimates", "order": 3}
]
}
headers: []
description: ''
responseFields: []
auth: []
controller: null
method: null
route: null
-
custom: []
httpMethods:
- GET
uri: api/projects
metadata:
custom: []
groupName: Projects
groupDescription: |-
Endpoints for managing projects.
subgroup: ''
subgroupDescription: ''
title: 'List all projects'
description: 'Get a list of all projects with optional filtering by status and type.'
title: 'List all team members'
description: 'Get a list of all team members with optional filtering by active status.'
authenticated: true
deprecated: false
headers:
@@ -120,31 +28,19 @@ endpoints:
urlParameters: []
cleanUrlParameters: []
queryParameters:
status_id:
active:
custom: []
name: status_id
description: 'Filter by status ID.'
name: active
description: 'Filter by active status.'
required: false
example: 1
type: integer
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
type_id:
custom: []
name: type_id
description: 'Filter by type ID.'
required: false
example: 2
type: integer
example: true
type: boolean
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanQueryParameters:
status_id: 1
type_id: 2
active: true
bodyParameters: []
cleanBodyParameters: []
fileParameters: []
@@ -157,12 +53,13 @@ endpoints:
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"code": "PROJ-001",
"title": "Client Dashboard Redesign",
"status": {"id": 1, "name": "Pre-sales"},
"type": {"id": 2, "name": "Support"},
"approved_estimate": "120.00",
"forecasted_effort": {"2024-02": 40, "2024-03": 60, "2024-04": 20},
"name": "John Doe",
"role": {
"id": 1,
"name": "Backend Developer"
},
"hourly_rate": "150.00",
"active": true,
"created_at": "2024-01-15T10:00:00.000000Z",
"updated_at": "2024-01-15T10:00:00.000000Z"
}
@@ -179,17 +76,17 @@ endpoints:
custom: []
httpMethods:
- POST
uri: api/projects
uri: api/team-members
metadata:
custom: []
groupName: Projects
groupName: 'Team Members'
groupDescription: |-
Endpoints for managing projects.
Endpoints for managing team members.
subgroup: ''
subgroupDescription: ''
title: 'Create a new project'
description: 'Create a new project with code, title, and type.'
title: 'Create a new team member'
description: 'Create a new team member with name, role, and hourly rate.'
authenticated: true
deprecated: false
headers:
@@ -200,32 +97,21 @@ endpoints:
queryParameters: []
cleanQueryParameters: []
bodyParameters:
code:
name:
custom: []
name: code
description: 'Project code (must be unique).'
name: name
description: 'Team member name.'
required: true
example: PROJ-001
example: 'John Doe'
type: string
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
title:
role_id:
custom: []
name: title
description: 'Project title.'
required: true
example: 'Client Dashboard Redesign'
type: string
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
type_id:
custom: []
name: type_id
description: 'Project type ID.'
name: role_id
description: 'Role ID.'
required: true
example: 1
type: integer
@@ -233,10 +119,33 @@ endpoints:
exampleWasSpecified: true
nullable: false
deprecated: false
hourly_rate:
custom: []
name: hourly_rate
description: 'Hourly rate (must be > 0).'
required: true
example: '150.00'
type: numeric
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
active:
custom: []
name: active
description: 'Active status (defaults to true).'
required: false
example: true
type: boolean
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanBodyParameters:
code: PROJ-001
title: 'Client Dashboard Redesign'
type_id: 1
name: 'John Doe'
role_id: 1
hourly_rate: '150.00'
active: true
fileParameters: []
responses:
-
@@ -246,10 +155,15 @@ endpoints:
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"code": "PROJ-001",
"title": "Client Dashboard Redesign",
"status": {"id": 1, "name": "Pre-sales"},
"type": {"id": 1, "name": "Project"}
"name": "John Doe",
"role": {
"id": 1,
"name": "Backend Developer"
},
"hourly_rate": "150.00",
"active": true,
"created_at": "2024-01-15T10:00:00.000000Z",
"updated_at": "2024-01-15T10:00:00.000000Z"
}
}
headers: []
@@ -257,7 +171,7 @@ endpoints:
-
custom: []
status: 422
content: '{"message":"Validation failed","errors":{"code":["Project code must be unique"],"title":["The title field is required."]}}'
content: '{"message":"Validation failed","errors":{"name":["The name field is required."],"hourly_rate":["Hourly rate must be greater than 0"]}}'
headers: []
description: ''
responseFields: []
@@ -269,17 +183,17 @@ endpoints:
custom: []
httpMethods:
- GET
uri: 'api/projects/{id}'
uri: 'api/team-members/{id}'
metadata:
custom: []
groupName: Projects
groupName: 'Team Members'
groupDescription: |-
Endpoints for managing projects.
Endpoints for managing team members.
subgroup: ''
subgroupDescription: ''
title: 'Get a single project'
description: 'Get details of a specific project by ID.'
title: 'Get a single team member'
description: 'Get details of a specific team member by ID.'
authenticated: true
deprecated: false
headers:
@@ -289,7 +203,7 @@ endpoints:
id:
custom: []
name: id
description: 'Project UUID.'
description: 'Team member UUID.'
required: true
example: 550e8400-e29b-41d4-a716-446655440000
type: string
@@ -312,12 +226,15 @@ endpoints:
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"code": "PROJ-001",
"title": "Client Dashboard Redesign",
"status": {"id": 1, "name": "Pre-sales"},
"type": {"id": 1, "name": "Project"},
"approved_estimate": "120.00",
"forecasted_effort": {"2024-02": 40, "2024-03": 60}
"name": "John Doe",
"role": {
"id": 1,
"name": "Backend Developer"
},
"hourly_rate": "150.00",
"active": true,
"created_at": "2024-01-15T10:00:00.000000Z",
"updated_at": "2024-01-15T10:00:00.000000Z"
}
}
headers: []
@@ -325,7 +242,7 @@ endpoints:
-
custom: []
status: 404
content: '{"message":"Project not found"}'
content: '{"message":"Team member not found"}'
headers: []
description: ''
responseFields: []
@@ -338,17 +255,17 @@ endpoints:
httpMethods:
- PUT
- PATCH
uri: 'api/projects/{id}'
uri: 'api/team-members/{id}'
metadata:
custom: []
groupName: Projects
groupName: 'Team Members'
groupDescription: |-
Endpoints for managing projects.
Endpoints for managing team members.
subgroup: ''
subgroupDescription: ''
title: 'Update a project'
description: 'Update details of an existing project.'
title: 'Update a team member'
description: 'Update details of an existing team member.'
authenticated: true
deprecated: false
headers:
@@ -358,7 +275,7 @@ endpoints:
id:
custom: []
name: id
description: 'Project UUID.'
description: 'Team member UUID.'
required: true
example: 550e8400-e29b-41d4-a716-446655440000
type: string
@@ -371,43 +288,55 @@ endpoints:
queryParameters: []
cleanQueryParameters: []
bodyParameters:
code:
name:
custom: []
name: code
description: 'Project code (must be unique).'
name: name
description: 'Team member name.'
required: false
example: PROJ-002
example: 'John Doe'
type: string
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
title:
role_id:
custom: []
name: title
description: 'Project title.'
name: role_id
description: 'Role ID.'
required: false
example: 'Updated Title'
type: string
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
type_id:
custom: []
name: type_id
description: 'Project type ID.'
required: false
example: 2
example: 1
type: integer
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
hourly_rate:
custom: []
name: hourly_rate
description: 'Hourly rate (must be > 0).'
required: false
example: '175.00'
type: numeric
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
active:
custom: []
name: active
description: 'Active status.'
required: false
example: false
type: boolean
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanBodyParameters:
code: PROJ-002
title: 'Updated Title'
type_id: 2
name: 'John Doe'
role_id: 1
hourly_rate: '175.00'
active: false
fileParameters: []
responses:
-
@@ -417,9 +346,15 @@ endpoints:
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"code": "PROJ-002",
"title": "Updated Title",
"type": {"id": 2, "name": "Support"}
"name": "John Doe",
"role": {
"id": 1,
"name": "Backend Developer"
},
"hourly_rate": "175.00",
"active": false,
"created_at": "2024-01-15T10:00:00.000000Z",
"updated_at": "2024-01-15T11:00:00.000000Z"
}
}
headers: []
@@ -427,13 +362,13 @@ endpoints:
-
custom: []
status: 404
content: '{"message":"Project not found"}'
content: '{"message":"Team member not found"}'
headers: []
description: ''
-
custom: []
status: 422
content: '{"message":"Validation failed","errors":{"type_id":["The selected type id is invalid."]}}'
content: '{"message":"Validation failed","errors":{"hourly_rate":["Hourly rate must be greater than 0"]}}'
headers: []
description: ''
responseFields: []
@@ -445,17 +380,17 @@ endpoints:
custom: []
httpMethods:
- DELETE
uri: 'api/projects/{id}'
uri: 'api/team-members/{id}'
metadata:
custom: []
groupName: Projects
groupName: 'Team Members'
groupDescription: |-
Endpoints for managing projects.
Endpoints for managing team members.
subgroup: ''
subgroupDescription: ''
title: 'Delete a project'
description: 'Delete a project. Cannot delete if project has allocations or actuals.'
title: 'Delete a team member'
description: 'Delete a team member. Cannot delete if member has allocations or actuals.'
authenticated: true
deprecated: false
headers:
@@ -465,7 +400,7 @@ endpoints:
id:
custom: []
name: id
description: 'Project UUID.'
description: 'Team member UUID.'
required: true
example: 550e8400-e29b-41d4-a716-446655440000
type: string
@@ -484,302 +419,25 @@ endpoints:
-
custom: []
status: 200
content: '{"message":"Project deleted successfully"}'
content: '{"message":"Team member deleted successfully"}'
headers: []
description: ''
-
custom: []
status: 404
content: '{"message":"Project not found"}'
content: '{"message":"Team member not found"}'
headers: []
description: ''
-
custom: []
status: 422
content: '{"message":"Cannot delete project with allocations"}'
headers: []
description: ''
responseFields: []
auth: []
controller: null
method: null
route: null
-
custom: []
httpMethods:
- PUT
uri: 'api/projects/{project}/status'
metadata:
custom: []
groupName: Projects
groupDescription: |-
Endpoints for managing projects.
subgroup: ''
subgroupDescription: ''
title: 'Transition project status'
description: 'Transition project to a new status following the state machine rules.'
authenticated: true
deprecated: false
headers:
Content-Type: application/json
Accept: application/json
urlParameters:
project:
custom: []
name: project
description: 'The project.'
required: true
example: architecto
type: string
enumValues: []
exampleWasSpecified: false
nullable: false
deprecated: false
id:
custom: []
name: id
description: 'Project UUID.'
required: true
example: 550e8400-e29b-41d4-a716-446655440000
type: string
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanUrlParameters:
project: architecto
id: 550e8400-e29b-41d4-a716-446655440000
queryParameters: []
cleanQueryParameters: []
bodyParameters:
status_id:
custom: []
name: status_id
description: 'Target status ID.'
required: true
example: 2
type: integer
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanBodyParameters:
status_id: 2
fileParameters: []
responses:
-
custom: []
status: 200
content: |-
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": {"id": 2, "name": "SOW Approval"}
}
}
headers: []
description: ''
-
custom: []
status: 404
content: '{"message":"Project not found"}'
headers: []
description: ''
-
custom: []
status: 422
content: '{"message":"Cannot transition from Pre-sales to Done"}'
headers: []
description: ''
responseFields: []
auth: []
controller: null
method: null
route: null
-
custom: []
httpMethods:
- PUT
uri: 'api/projects/{project}/estimate'
metadata:
custom: []
groupName: Projects
groupDescription: |-
Endpoints for managing projects.
subgroup: ''
subgroupDescription: ''
title: 'Set approved estimate'
description: 'Set the approved billable hours estimate for a project.'
authenticated: true
deprecated: false
headers:
Content-Type: application/json
Accept: application/json
urlParameters:
project:
custom: []
name: project
description: 'The project.'
required: true
example: architecto
type: string
enumValues: []
exampleWasSpecified: false
nullable: false
deprecated: false
id:
custom: []
name: id
description: 'Project UUID.'
required: true
example: 550e8400-e29b-41d4-a716-446655440000
type: string
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanUrlParameters:
project: architecto
id: 550e8400-e29b-41d4-a716-446655440000
queryParameters: []
cleanQueryParameters: []
bodyParameters:
approved_estimate:
custom: []
name: approved_estimate
description: 'Approved estimate hours (must be > 0).'
required: true
example: 120.0
type: number
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanBodyParameters:
approved_estimate: 120.0
fileParameters: []
responses:
-
custom: []
status: 200
content: |-
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"approved_estimate": "120.00"
}
}
headers: []
description: ''
-
custom: []
status: 404
content: '{"message":"Project not found"}'
headers: []
description: ''
-
custom: []
status: 422
content: '{"message":"Approved estimate must be greater than 0"}'
headers: []
description: ''
responseFields: []
auth: []
controller: null
method: null
route: null
-
custom: []
httpMethods:
- PUT
uri: 'api/projects/{project}/forecast'
metadata:
custom: []
groupName: Projects
groupDescription: |-
Endpoints for managing projects.
subgroup: ''
subgroupDescription: ''
title: 'Set forecasted effort'
description: 'Set the month-by-month forecasted effort breakdown.'
authenticated: true
deprecated: false
headers:
Content-Type: application/json
Accept: application/json
urlParameters:
project:
custom: []
name: project
description: 'The project.'
required: true
example: architecto
type: string
enumValues: []
exampleWasSpecified: false
nullable: false
deprecated: false
id:
custom: []
name: id
description: 'Project UUID.'
required: true
example: 550e8400-e29b-41d4-a716-446655440000
type: string
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanUrlParameters:
project: architecto
id: 550e8400-e29b-41d4-a716-446655440000
queryParameters: []
cleanQueryParameters: []
bodyParameters:
forecasted_effort:
custom: []
name: forecasted_effort
description: 'Monthly effort breakdown.'
required: true
example:
2024-02: 40
2024-03: 60
type: object
enumValues: []
exampleWasSpecified: true
nullable: false
deprecated: false
cleanBodyParameters:
forecasted_effort:
2024-02: 40
2024-03: 60
fileParameters: []
responses:
-
custom: []
status: 200
content: |-
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"forecasted_effort": {"2024-02": 40, "2024-03": 60}
}
}
headers: []
description: ''
-
custom: []
status: 404
content: '{"message":"Project not found"}'
headers: []
description: ''
-
custom: []
status: 422
content: '{"message":"Forecasted effort exceeds approved estimate by more than 5%"}'
content: '{"message":"Cannot delete team member with active allocations","suggestion":"Consider deactivating the team member instead"}'
headers: []
description: ''
-
custom: []
status: 422
content: '{"message":"Cannot delete team member with historical data","suggestion":"Consider deactivating the team member instead"}'
headers: []
description: ''
responseFields: []