InfraForge Docs

InfraNotes Finance Project · v0.6.0

Welcome

Select a document from the sidebar to read it.

Project Finance API Endpoints

Version: 1.1
Base URL: https://gateway.infraforg.com
Authentication: Bearer Token (JWT)
Status: 71/73 endpoints operational (97%)
Last Tested: 2025-12-19

Table of Contents

Project Finance

Create Project Finance

POST /api/project-finance

Creates a new project finance record.

Request:

{
  "project_id": "3d0d8511-2cc5-425a-8f52-0704f730e9c7",
  "total_budget": {
    "amount": 100000,
    "currency": "USD"
  },
  "revenue_model": "fixed_price"
}

Revenue Models: fixed_price, time_and_materials, milestone_based, retainer

Response: 201 Created

{
  "id": "8f69cb8b-34f1-4782-ab1f-c907a8142410",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "3d0d8511-2cc5-425a-8f52-0704f730e9c7",
  "total_budget": {"amount": 100000, "currency": "USD"},
  "allocated_budget": {"amount": 0, "currency": "USD"},
  "revenue_model": "FIXED_PRICE",
  "health_status": "HEALTHY",
  "risk_level": "LOW",
  "financial_health_score": {"score": 100},
  "created_at": "2025-12-18T10:29:48Z"
}

List Project Finances

GET /api/project-finance?limit=10&offset=0

Returns paginated list of project finance records.

Query Parameters:

  • limit (optional): Number of records (default: 10)
  • offset (optional): Pagination offset (default: 0)

Response: 200 OK

{
  "items": [{ /* project finance object */ }],
  "total": 25,
  "limit": 10,
  "offset": 0
}

Get Project Finance by ID

GET /api/project-finance/{id}

Retrieves a specific project finance record.

Response: 200 OK

Update Project Finance

PUT /api/project-finance/{id}

Updates a project finance record.

Headers:

  • If-Match: * (required for optimistic concurrency)

Request:

{
  "revenue_model": "milestone_based"
}

Response: 200 OK

Delete Project Finance

DELETE /api/project-finance/{id}

Deletes a project finance record.

Headers:

  • If-Match: * (required)

Response: 204 No Content

Allocate Budget

POST /api/project-finance/{id}/allocate-budget

Allocates budget from total to a specific allocation.

Request:

{
  "amount": {
    "amount": 25000,
    "currency": "USD"
  }
}

Response: 204 No Content

Commit Budget

POST /api/project-finance/{id}/commit-budget

Commits allocated budget for expenditure.

Request:

{
  "amount": {
    "amount": 10000,
    "currency": "USD"
  }
}

Response: 204 No Content

Record Cost

POST /api/project-finance/{id}/record-cost

Records actual cost against the project.

Request:

{
  "amount": {
    "amount": 1000,
    "currency": "USD"
  }
}

Response: 204 No Content

Recognize Revenue

POST /api/project-finance/{id}/recognize-revenue

Records recognized revenue for the project.

Request:

{
  "amount": {
    "amount": 500,
    "currency": "USD"
  }
}

Response: 204 No Content

Get Child Projects

GET /api/project-finance/{id}/children

Returns child projects in the hierarchy.

Response: 200 OK

{
  "children": [
    {
      "id": "uuid",
      "project_id": "uuid",
      "total_budget": {"amount": 50000, "currency": "USD"}
    }
  ]
}

Phases

Create Phase

POST /api/project-finance/{pf_id}/phases

Creates a new phase for a project.

Request:

{
  "name": "Planning",
  "sequence": 1,
  "phase_budget": {
    "amount": 30000,
    "currency": "USD"
  },
  "planned_start": "2025-12-18T00:00:00Z",
  "planned_end": "2026-01-18T00:00:00Z"
}

Response: 201 Created

{
  "id": "8dcc78b6-a48e-4419-b72e-34217278d0a2",
  "project_finance_id": "8f69cb8b-34f1-4782-ab1f-c907a8142410",
  "name": "Planning",
  "status": "PENDING",
  "sequence": 1,
  "phase_budget": {"amount": 30000, "currency": "USD"},
  "completion_percent": 0
}

Get Phase by ID

GET /api/phases/{id}

Retrieves a specific phase.

Response: 200 OK

List Phases

GET /api/project-finance/{pf_id}/phases

Returns all phases for a project.

Response: 200 OK

{
  "phases": [{ /* phase object */ }]
}

Update Phase

PUT /api/phases/{id}

Updates phase details.

Request:

{
  "name": "Planning Updated"
}

Response: 200 OK

Delete Phase

DELETE /api/phases/{id}

Deletes a phase.

Headers:

  • If-Match: * (required)

Response: 204 No Content

Start Phase

POST /api/phases/{id}/start

Transitions phase to IN_PROGRESS status.

Response: 201 Created

Update Phase Progress

POST /api/phases/{id}/progress

Updates phase completion percentage.

Request:

{
  "percent": 50
}

Response: 201 Created

Complete Phase

POST /api/phases/{id}/complete

Marks phase as completed.

Response: 201 Created

Milestones

Create Milestone

POST /api/project-finance/{pf_id}/milestones

Creates a new milestone.

Request:

{
  "name": "M1 - Requirements Complete",
  "sequence": 1,
  "amount": {
    "amount": 15000,
    "currency": "USD"
  },
  "due_date": "2025-12-31T00:00:00Z",
  "description": "All requirements gathered and approved"
}

Response: 201 Created

{
  "id": "51e9db10-7a26-4ac5-9a3d-b8eba5c90e6d",
  "project_finance_id": "8f69cb8b-34f1-4782-ab1f-c907a8142410",
  "name": "M1 - Requirements Complete",
  "status": "PENDING",
  "sequence": 1,
  "amount": {"amount": 15000, "currency": "USD"},
  "completion_percent": 0
}

Get Milestone by ID

GET /api/milestones/{id}

Retrieves a specific milestone.

Response: 200 OK

List Milestones

GET /api/project-finance/{pf_id}/milestones

Returns all milestones for a project.

Response: 200 OK

Update Milestone

PUT /api/milestones/{id}

Updates milestone details.

Request:

{
  "name": "M1 - Requirements Complete (Updated)",
  "due_date": "2026-01-15T00:00:00Z"
}

Response: 200 OK

Delete Milestone

DELETE /api/milestones/{id}

Deletes a milestone.

Headers:

  • If-Match: * (required)

Response: 204 No Content

Update Milestone Progress

POST /api/milestones/{id}/progress

Updates milestone completion percentage.

Request:

{
  "completion_percent": 75
}

Response: 201 Created

Complete Milestone

POST /api/milestones/{id}/complete

Marks milestone as completed.

Response: 201 Created

Cancel Milestone

POST /api/milestones/{id}/cancel

Cancels a pending or in-progress milestone.

Response: 201 Created

Note: Cannot cancel completed or billed milestones.

Cost Centers

Create Cost Center

POST /api/project-finance/{pf_id}/cost-centers

Creates a new cost center for budget allocation.

Request:

{
  "code": "LAB",
  "name": "Labor",
  "description": "Labor costs",
  "allocated_budget": {
    "amount": 50000,
    "currency": "USD"
  }
}

Response: 201 Created

{
  "id": "2b9ef63a-9dec-47a4-9d36-dbdf7b50d058",
  "project_finance_id": "8f69cb8b-34f1-4782-ab1f-c907a8142410",
  "code": "LAB",
  "name": "Labor",
  "allocated_budget": {"amount": 50000, "currency": "USD"},
  "actual_cost": {"amount": 0, "currency": "USD"}
}

Common Codes: LAB (Labor), MAT (Materials), EQP (Equipment), OVHD (Overhead)

Get Cost Center by ID

GET /api/cost-centers/{id}

Retrieves a specific cost center.

Response: 200 OK

List Cost Centers

GET /api/project-finance/{pf_id}/cost-centers

Returns all cost centers for a project.

Response: 200 OK

Update Cost Center

PUT /api/cost-centers/{id}

Updates cost center details.

Request:

{
  "name": "Labor - Engineering",
  "description": "Engineering labor costs"
}

Response: 200 OK

Allocate Cost Center Budget

POST /api/cost-centers/{id}/allocate-budget

Allocates additional budget to a cost center.

Request:

{
  "amount": {
    "amount": 10000,
    "currency": "USD"
  }
}

Response: 201 Created

Templates

Create Template

POST /api/project-finance/templates

Creates a new project finance template.

Request:

{
  "name": "Standard Web Project",
  "description": "Template for web development projects",
  "category": "web_development",
  "default_budget": {
    "amount": 100000,
    "currency": "USD"
  },
  "default_revenue_model": "milestone_based",
  "estimated_duration_days": 90,
  "is_public": false,
  "template_data": {
    "phases": [
      {
        "name": "Planning",
        "sequence": 1,
        "budget_amount": 20000
      },
      {
        "name": "Development",
        "sequence": 2,
        "budget_amount": 60000
      },
      {
        "name": "Testing",
        "sequence": 3,
        "budget_amount": 20000
      }
    ],
    "cost_centers": [
      {"code": "LAB", "name": "Labor", "budget_amount": 70000},
      {"code": "INFRA", "name": "Infrastructure", "budget_amount": 30000}
    ]
  }
}

Response: 201 Created

{
  "id": "9df6a557-9dbc-421f-b8e5-bafcf7ebb1e1",
  "name": "Standard Web Project",
  "category": "web_development",
  "default_budget": {"amount": 100000, "currency": "USD"},
  "is_public": false,
  "created_at": "2025-12-18T11:15:30Z"
}

List Templates

GET /api/project-finance/templates

Returns all available templates.

Query Parameters:

  • category (optional): Filter by category
  • is_public (optional): Filter by visibility

Response: 200 OK

Get Template by ID

GET /api/project-finance/templates/{id}

Retrieves a specific template.

Response: 200 OK

Update Template

PUT /api/project-finance/templates/{id}

Updates template details.

Request:

{
  "name": "Standard Web Project v2",
  "description": "Updated template"
}

Response: 200 OK

Delete Template

DELETE /api/project-finance/templates/{id}

Deletes a template.

Headers:

  • If-Match: * (required)

Response: 204 No Content

Apply Template

POST /api/project-finance/templates/{id}/apply

Applies a template to an existing project finance record, creating pre-configured phases, milestones, and cost centers.

Path Parameters:

  • id: Template ID (UUID)

Request:

{
  "project_finance_id": "0d2508fa-3810-44dd-83da-d4396c2203d8"
}

Response: 201 Created

{
  "message": "Template applied successfully",
  "project_finance_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "template_id": "e2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

Capacity & Dashboard

Get Project Capacity

GET /api/project-finance/project/{projectID}/capacity

Returns capacity metrics for a specific project.

Response: 200 OK

{
  "project_id": "3d0d8511-2cc5-425a-8f52-0704f730e9c7",
  "total_capacity": 160,
  "allocated_capacity": 120,
  "available_capacity": 40,
  "utilization_percent": 75.0,
  "team_members": [
    {
      "user_id": "uuid",
      "capacity_percent": 50,
      "hours_allocated": 80
    }
  ]
}

Get Portfolio Capacity

GET /api/project-finance/portfolio/capacity

Returns capacity metrics across all projects.

Response: 200 OK

Get Project Dashboard

GET /api/project-finance/project/{projectID}/dashboard

Returns comprehensive dashboard data for a project.

Response: 200 OK

{
  "project_id": "3d0d8511-2cc5-425a-8f52-0704f730e9c7",
  "financial_summary": {
    "total_budget": {"amount": 100000, "currency": "USD"},
    "actual_cost": {"amount": 1000, "currency": "USD"},
    "budget_variance": {"amount": 99000, "currency": "USD"},
    "budget_variance_percent": 99.0
  },
  "phase_summary": {
    "total_phases": 3,
    "completed_phases": 1,
    "in_progress_phases": 1,
    "pending_phases": 1
  },
  "milestone_summary": {
    "total_milestones": 5,
    "completed_milestones": 2,
    "upcoming_milestones": 3
  },
  "health_metrics": {
    "health_status": "HEALTHY",
    "risk_level": "LOW",
    "financial_health_score": 95
  }
}

Get Portfolio Dashboard

GET /api/project-finance/portfolio/dashboard

Returns portfolio-level dashboard with aggregated metrics.

Response: 200 OK

Team Members

Add Team Member

POST /api/project-finance/{pf_id}/team

Adds a team member to the project.

Request:

{
  "user_id": "a7b8c9d0-1234-5678-9abc-def012345678",
  "role": "developer",
  "capacity_percent": 50,
  "hourly_rate": {
    "amount": 75,
    "currency": "USD"
  },
  "is_billable": true,
  "start_date": "2025-12-18T00:00:00Z"
}

Roles: project_manager, technical_lead, developer, designer, qa_engineer, business_analyst, stakeholder

Response: 201 Created

{
  "id": "3a6c6a57-faaa-4d25-aaee-8136cb1e8d41",
  "project_finance_id": "8f69cb8b-34f1-4782-ab1f-c907a8142410",
  "user_id": "a7b8c9d0-1234-5678-9abc-def012345678",
  "role": "developer",
  "capacity_percent": 50,
  "hourly_rate": {"amount": 75, "currency": "USD"},
  "is_billable": true,
  "total_hours_logged": 0,
  "start_date": "2025-12-18T00:00:00Z"
}

Get Team Member by ID

GET /api/team/{id}

Retrieves a specific team member.

Response: 200 OK

List Team Members

GET /api/project-finance/{pf_id}/team

Returns all team members for a project.

Response: 200 OK

Update Team Member

PUT /api/team/{id}

Updates team member details.

Headers:

  • If-Match: * (required)

Request:

{
  "capacity_percent": 75,
  "hourly_rate": {
    "amount": 85,
    "currency": "USD"
  }
}

Response: 200 OK

Remove Team Member

DELETE /api/team/{id}

Removes a team member from the project.

Headers:

  • If-Match: * (required)

Response: 204 No Content

Log Hours

POST /api/team/{id}/log-hours

Logs work hours for a team member.

Request:

{
  "hours": 8.5
}

Response: 201 Created

Scope Changes

Create Scope Change

POST /api/project-finance/{pf_id}/scope-changes

Creates a new scope change request.

Request:

{
  "requested_by": "eeedef43-5389-5797-85f2-aff447d403c8",
  "title": "Add User Authentication",
  "description": "Implement OAuth2 authentication system",
  "change_type": "addition",
  "budget_impact": {
    "amount": 15000,
    "currency": "USD"
  },
  "timeline_impact": 14
}

Change Types: addition, removal, modification

Response: 201 Created

{
  "id": "ff318cad-c17f-4e34-9571-33b871e152fe",
  "project_finance_id": "8f69cb8b-34f1-4782-ab1f-c907a8142410",
  "title": "Add User Authentication",
  "status": "DRAFT",
  "change_type": "addition",
  "budget_impact": {"amount": 15000, "currency": "USD"},
  "timeline_impact": 14,
  "created_at": "2025-12-18T10:35:00Z"
}

Get Scope Change by ID

GET /api/scope-changes/{id}

Retrieves a specific scope change.

Response: 200 OK

List Scope Changes

GET /api/project-finance/{pf_id}/scope-changes

Returns all scope changes for a project.

Query Parameters:

  • status (optional): Filter by status (DRAFT, SUBMITTED, APPROVED, REJECTED)

Response: 200 OK

Update Scope Change

PUT /api/scope-changes/{id}

Updates scope change details (only in DRAFT status).

Request:

{
  "title": "Add User Authentication - Updated",
  "budget_impact": {
    "amount": 18000,
    "currency": "USD"
  }
}

Response: 200 OK

Submit Scope Change

POST /api/scope-changes/{id}/submit

Submits scope change for approval.

Response: 201 Created

Approve Scope Change

POST /api/scope-changes/{id}/approve

Approves a submitted scope change.

Request:

{
  "reason": "Approved by steering committee"
}

Response: 201 Created

Reject Scope Change

POST /api/scope-changes/{id}/reject

Rejects a submitted scope change.

Request:

{
  "reason": "Not aligned with project goals"
}

Response: 201 Created

Delete Scope Change

DELETE /api/scope-changes/{id}

Deletes a scope change (only in DRAFT status).

Headers:

  • If-Match: * (required)

Response: 204 No Content

Note: Cannot delete scope changes that have been submitted, approved, or rejected.

Analytics

Get Project Health

GET /api/analytics/projects/{project_id}/health

Returns health metrics for a specific project.

Path Parameters:

  • project_id: The Core project ID (UUID)

Response: 200 OK

{
  "project_id": "9ee6ddf5-27d9-4bca-99f4-d46961c97fe5",
  "health_status": "HEALTHY",
  "risk_level": "LOW",
  "financial_health_score": 85,
  "schedule_health_score": 90,
  "scope_health_score": 95,
  "overall_health_score": 90,
  "risk_factors": [],
  "recommendations": []
}

Get Portfolio Analytics

GET /api/analytics/portfolio

Returns portfolio-level financial analytics.

Query Parameters:

  • period (optional): last_7_days, last_30_days, last_90_days, current_year

Response: 200 OK

{
  "summary": {
    "total_projects": 25,
    "total_budget": {"amount": 2500000, "currency": "USD"},
    "total_actual_cost": {"amount": 1850000, "currency": "USD"},
    "total_revenue": {"amount": 2100000, "currency": "USD"},
    "average_health_score": 87
  },
  "by_status": {
    "healthy": 18,
    "at_risk": 5,
    "critical": 2
  },
  "by_revenue_model": {
    "fixed_price": 10,
    "time_and_materials": 8,
    "milestone_based": 5,
    "retainer": 2
  },
  "trends": {
    "budget_variance_trend": "improving",
    "cost_performance_index": 1.15
  }
}

Generate Project Forecast

POST /api/analytics/projects/{project_id}/forecast

Generates financial forecast for a project.

Path Parameters:

  • project_id: The Core project ID (UUID)

Request:

{
  "period": "3_months"
}

Periods: 3_months, 6_months, 12_months

Response: 201 Created

{
  "project_id": "9ee6ddf5-27d9-4bca-99f4-d46961c97fe5",
  "forecast_period": "3_months",
  "generated_at": "2025-12-19T00:20:00Z",
  "projected_cost": {"amount": 75000, "currency": "USD"},
  "projected_revenue": {"amount": 85000, "currency": "USD"},
  "confidence_level": 0.85,
  "risk_adjusted_cost": {"amount": 82500, "currency": "USD"}
}

Compliance

Generate SOX-404 Report

POST /api/compliance/reports/sox-404

Generates a SOX Section 404 compliance report.

Request:

{
  "project_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-12-31T23:59:59Z"
}

Note: project_id is optional. If omitted, generates portfolio-wide report.

Response: 201 Created

{
  "report_id": "rpt_sox404_1766104214_550e8400",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "report_period": {
    "start_date": "2025-01-01T00:00:00Z",
    "end_date": "2025-12-31T23:59:59Z"
  },
  "generated_at": "2025-12-19T00:30:14Z",
  "framework": "SOX_404",
  "budget_controls": [...],
  "revenue_recognition": [...],
  "expense_approvals": [...],
  "change_order_controls": [...],
  "compliance_attestations": [...],
  "total_controls": 7,
  "effective_controls": 4,
  "deficient_controls": 3,
  "control_effectiveness": 57.14
}

Generate GDPR Article 30 Report

POST /api/compliance/reports/gdpr-article-30

Generates a GDPR Article 30 Records of Processing Activities report.

Request:

{
  "project_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-12-31T23:59:59Z"
}

Response: 201 Created

{
  "report_id": "rpt_gdpr30_1766104214_550e8400",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "report_period": {...},
  "generated_at": "2025-12-19T00:30:14Z",
  "framework": "GDPR_ARTICLE_30",
  "data_processing_activities": [...],
  "personal_data_categories": [...],
  "data_subjects": [...],
  "legal_basis": "Legitimate interest (Article 6(1)(f))",
  "retention_period": "7 years from project completion",
  "technical_measures": [...],
  "organizational_measures": [...]
}

Generate Audit Trail Report

POST /api/compliance/reports/audit-trail

Generates an audit trail report for compliance purposes.

Request:

{
  "project_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-12-31T23:59:59Z",
  "event_types": ["budget_allocation", "scope_change_approval"],
  "user_id": "eeedef43-5389-5797-85f2-aff447d403c8"
}

Note: event_types and user_id are optional filters.

Response: 201 Created

{
  "report_id": "rpt_audit_1766104214_550e8400",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "report_period": {...},
  "generated_at": "2025-12-19T00:30:14Z",
  "audit_entries": [...],
  "total_entries": 125,
  "unique_users": 8,
  "event_types": {
    "budget_allocation": 45,
    "scope_change_approval": 12,
    "phase_complete": 8
  }
}

Export

Export Project Data

POST /api/export

Exports project finance data in specified format.

Request:

{
  "project_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "format": "json",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-12-31T23:59:59Z",
  "include_phases": true,
  "include_team": true,
  "include_scopes": true
}

Note: project_id uses the Project Finance ID (not Core project ID). All date and include fields are optional.

Formats: json, csv, excel

Response: 201 Created

{
  "export_id": "exp_1766104285_550e8400_f18a013f",
  "format": "json",
  "file_size": 7245,
  "record_count": 1,
  "generated_at": "2025-12-19T00:31:25Z",
  "expires_at": "2025-12-20T00:31:25Z"
}

Invoice Orchestration

Bill Progress

POST /api/project-finance/{id}/bill-progress

Creates a progress-based invoice for the project.

Path Parameters:

  • id: Project Finance ID (UUID)

Request:

{
  "progress_percent": 50
}

Response: 201 Created

Note: Only available for projects with MILESTONE_BASED or TIME_AND_MATERIALS revenue models. Projects with FIXED_PRICE billing will receive error: "project finance must use MILESTONE_BASED or TIME_AND_MATERIALS billing model".

Invoice Milestone

POST /api/milestones/{id}/invoice

Creates an invoice for a completed milestone using saga orchestration.

Path Parameters:

  • id: Milestone ID (UUID)

Response: 201 Created

{
  "invoice_id": "inv-uuid",
  "milestone_id": "46b4488f-0d54-402e-ac6f-85e1a8a42076",
  "amount": {"amount": 15000, "currency": "USD"},
  "status": "PENDING",
  "saga_id": "saga-uuid",
  "created_at": "2025-12-19T00:00:00Z"
}

Note: This endpoint orchestrates invoice creation through the billing service via saga pattern. Milestone must be in COMPLETED status.

Approval Workflow

Request Approval

POST /api/approvals

Creates a new approval request.

Request:

{
  "entity_type": "budget_allocation",
  "entity_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "description": "Budget allocation approval request",
  "amount": {
    "amount": 100000,
    "currency": "USD"
  },
  "metadata": {
    "project_name": "Website Redesign",
    "department": "Engineering"
  }
}

Entity Types: budget_allocation, scope_change, milestone_invoice, expense, resource_allocation

Response: 201 Created

{
  "id": "17c711e7-5577-4904-a79b-940be9f7e8bb",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_type": "budget_allocation",
  "entity_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "amount_minor": 10000000,
  "description": "Budget allocation approval request",
  "requester_id": "eeedef43-5389-5797-85f2-aff447d403c8",
  "status": "PENDING",
  "created_at": "2025-12-19T00:32:03Z",
  "updated_at": "2025-12-19T00:32:03Z"
}

Get Pending Approvals

GET /api/approvals/pending

Returns all pending approvals for the current user.

Response: 200 OK

[
  {
    "id": "17c711e7-5577-4904-a79b-940be9f7e8bb",
    "entity_type": "budget_allocation",
    "entity_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
    "amount_minor": 10000000,
    "description": "Budget allocation approval request",
    "requester_id": "eeedef43-5389-5797-85f2-aff447d403c8",
    "status": "PENDING",
    "created_at": "2025-12-19T00:32:03Z"
  }
]

Approve Request

POST /api/approvals/{id}/approve

Approves an approval request.

Path Parameters:

  • id: Approval Request ID (UUID)

Request:

{
  "notes": "Approved for budget allocation"
}

Response: 201 Created

Reject Request

POST /api/approvals/{id}/reject

Rejects an approval request.

Path Parameters:

  • id: Approval Request ID (UUID)

Request:

{
  "notes": "Rejected due to budget constraints"
}

Response: 201 Created

Cancel Request

POST /api/approvals/{id}/cancel

Cancels a pending approval request (by requester).

Path Parameters:

  • id: Approval Request ID (UUID)

Request:

{
  "notes": "Cancelled by requester"
}

Response: 201 Created

Get Entity Approval Status

GET /api/approvals/entity/{entity_type}/{entity_id}

Returns the latest approval status for a specific entity.

Path Parameters:

  • entity_type: Entity type (e.g., budget_allocation, scope_change)
  • entity_id: Entity ID (UUID)

Response: 200 OK

{
  "id": "17c711e7-5577-4904-a79b-940be9f7e8bb",
  "entity_type": "budget_allocation",
  "entity_id": "0d2508fa-3810-44dd-83da-d4396c2203d8",
  "amount_minor": 10000000,
  "description": "Budget allocation approval request",
  "requester_id": "eeedef43-5389-5797-85f2-aff447d403c8",
  "status": "APPROVED",
  "approver_id": "eeedef43-5389-5797-85f2-aff447d403c8",
  "approved_at": "2025-12-19T00:32:22Z",
  "notes": "Approved for budget allocation",
  "created_at": "2025-12-19T00:32:03Z",
  "updated_at": "2025-12-19T00:32:22Z"
}

Check If Approval Required

GET /api/approvals/check-required

Checks if approval is required for a specific entity type and amount.

Query Parameters:

  • entity_type: Entity type (required)
  • amount: Amount in minor units (required)

Example: /api/approvals/check-required?entity_type=budget_allocation&amount=10000000

Response: 200 OK

{
  "required": true
}

Common Patterns

Authentication

All endpoints require JWT Bearer token in Authorization header:

Authorization: Bearer <token>

Pagination

List endpoints support pagination:

  • limit: Items per page (default: 10, max: 100)
  • offset: Skip N items (default: 0)

Optimistic Concurrency

Update/Delete operations require If-Match header:

If-Match: *

Error Responses

Standard error format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {}
}

Common Status Codes:

  • 200 OK - Successful GET/PUT
  • 201 Created - Successful POST
  • 204 No Content - Successful DELETE
  • 400 Bad Request - Invalid input
  • 401 Unauthorized - Missing/invalid token
  • 404 Not Found - Resource doesn't exist
  • 500 Internal Server Error - Server error

Currency Format

All monetary values use:

{
  "amount": 10000,
  "currency": "USD"
}

Date Format

All timestamps use ISO 8601 format: 2025-12-18T10:29:48Z

Notes

  • Revenue Models: Input accepts lowercase (fixed_price), output returns uppercase (FIXED_PRICE)
  • Project IDs: Endpoints accept both Core project IDs (converted internally) and PF UUIDs
  • RLS: All operations enforce tenant isolation via Row-Level Security
  • Idempotency: POST operations support idempotency keys (via middleware)
  • Rate Limiting: 5000 requests per minute per API key

Last Updated: 2025-12-19
Operational Endpoints: 71/73 (97%)
Known Issues: 2 (Team Member ETag missing for PUT/DELETE)
Documentation Status: Production-Ready