API Contracts Documentation
Generated: 2025-11-16
Overview
This document catalogs all API endpoints in the Flowcode application, including both public APIs and SPA-specific routes.
Authentication
- Primary: Laravel Sanctum (auth:sanctum middleware)
- Web Sessions: auth:web middleware
- Multi-tenancy: Organization-scoped routes with tenant isolation
Public Calendar APIs (No Auth Required)
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/api/sessions/global |
SessionICalApiController@globalCalendar |
Global calendar feed |
| GET |
/api/sessions/guiding/{user} |
SessionICalApiController@guidingCalendar |
User's guiding calendar |
| GET |
/api/sessions/personal/{user} |
SessionICalApiController@personalCalendar |
User's personal calendar |
| GET |
/api/sessions/location/{delivery_location} |
SessionICalApiController@deliveryLocationCalendar |
Location-based calendar |
| GET |
/api/personal-sessions/{user} |
SessionICalApiController@personalCalendar |
Personal sessions feed |
SPA Session Management APIs (auth:web)
Prefix: /api/spa/sessions
| Method |
Endpoint |
Controller |
Purpose |
| POST |
/{engauge_session}/guides |
SessionApiController@addGuide |
Add guide to session |
| DELETE |
/{engauge_session}/guides/{userId} |
SessionApiController@removeGuide |
Remove guide from session |
| POST |
/{engauge_session}/facilitators |
SessionApiController@addFacilitator |
Add facilitator |
| DELETE |
/{engauge_session}/facilitators/{userId} |
SessionApiController@removeFacilitator |
Remove facilitator |
| POST |
/{engauge_session}/convenor |
SessionApiController@updateConvenor |
Update convenor |
| GET |
/group-availability |
SessionAvailabilityController@getWeekdayReservedTimesForGroupOfFacilitatorsAndGuides |
Check group availability |
SPA Core APIs (auth:sanctum)
Prefix: /api/spa
Roles
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/roles |
RoleController@fetchAll |
Fetch all roles |
OPTT Attachments
| Method |
Endpoint |
Controller |
Purpose |
| POST |
/optt-attachments |
OpttAttachmentController@store |
Upload attachment |
| DELETE |
/optt-attachments/{optt_attachment} |
OpttAttachmentController@destroy |
Delete attachment |
Organizations
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/organisations |
OrganisationController@fetchAll |
List all organizations |
| GET |
/organisations/{organisation}/users |
UserController@fetchForOrganisation |
Users in org |
| GET |
/organisations/{organisation}/roles |
OrganisationRoleController@fetchForOrganisation |
Org roles |
| GET |
/organisations/{organisation}/divisions |
DivisionController@fetchForOrganisation |
Org divisions |
| GET |
/organisations/{organisation}/departments |
DepartmentController@fetchForOrganisation |
Org departments |
| GET |
/organisations/{organisation}/elements |
ElementController@fetchForOrganisation |
Org elements |
| GET |
/organisations/{organisation}/objectives |
ObjectiveController@fetchForOrganisation |
Org objectives |
| GET |
/organisations/{organisation}/projects |
ProjectController@fetchForOrganisation |
Org projects |
| GET |
/organisations/{organisation}/tasks |
TaskController@fetchForOrganisation |
Org tasks |
Catalogue Element Fields (Complex nested data)
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/organisations/{org}/catalogues/{cat}/elements/{elem}/fields/{field}/progress |
ApiElementFieldController@progress |
Field progress data |
| GET |
/organisations/{org}/catalogues/{cat}/elements/{elem}/fields/{field}/nested |
ApiElementFieldController@getNestedIndices |
Nested field indices |
| GET |
/organisations/{org}/catalogues/{cat}/elements/{elem}/fields/{field}/calc/{index?} |
ApiElementFieldController@calc |
Field calculations |
| GET |
/organisations/{org}/elements/{elem}/fields/{field}/preview |
ApiElementFieldController@preview |
Field preview |
Catalogues
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/catalogues |
ApiCatalogueController@fetchAll |
All catalogues |
| GET |
/catalogues/published |
ApiCatalogueController@fetchPublished |
Published catalogues only |
Elements
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/elements |
ElementController@fetchAll |
All elements |
| GET |
/elements/{element}/{tab}/number |
FieldController@fetchNumberFieldsForElement |
Number fields |
| GET |
/elements/{element}/{tab}/numberAndCalculate/{field?} |
FieldController@fetchNumberAndCalculateFieldsForElement |
Number + calc fields |
| GET |
/elements/{element}/graphics/fields/{graphic_type} |
FieldController@fetchFieldsForGraphics |
Fields for graphics |
Fields
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/fields/linkable |
FieldController@fetchLinkableFields |
Linkable fields |
| GET |
/fields/linkable-children/{field} |
FieldController@fetchLinkableChildrenFields |
Child linkable fields |
| GET |
/fields/element/{element}/replicate |
FieldController@fetchReplicateFields |
Fields for replication |
| GET |
/fields/element/{element}/archived |
FieldController@fetchArchivedFields |
Archived fields |
Users
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/users |
UserController@fetchAll |
All users |
| GET |
/users/{user}/organisations |
UserOrganisationController@fetchAll |
User's orgs |
| GET |
/users/{user}/organisations/{org}/objectives |
ObjectiveController@fetchForOrganisationUser |
User objectives in org |
| GET |
/users/{user}/organisations/{org}/projects |
ProjectController@fetchForOrganisationUser |
User projects in org |
| GET |
/users/{user}/organisations/{org}/tasks |
TaskController@fetchForOrganisationUser |
User tasks in org |
Sessions
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/sessions/{session} |
SessionApiController@fetch |
Fetch single session |
Miscellaneous
| Method |
Endpoint |
Controller |
Purpose |
| POST |
/resource-assets/images/upload |
WysiwygUploadController@uploadImage |
WYSIWYG image upload |
| POST |
/heartbeat |
HeartbeatController@heartbeat |
Session heartbeat (no throttle) |
User Availability APIs (auth:web)
| Method |
Endpoint |
Controller |
Purpose |
| GET |
/api/users/guides/available |
UserController@fetchAvailableGuides |
Available guides |
| GET |
/api/users/facilitators/available |
UserController@fetchAvailableFacilitators |
Available facilitators |
| GET |
/api/users/convenors/available |
UserController@fetchAvailableConvenors |
Available convenors |
Export APIs (Public, token-based)
| Method |
Endpoint |
Purpose |
| GET |
/api/organisations/{org}/catalogues/{cat}/elements/{elem}/fields/{field}/progress |
Progress export |
| GET |
/api/organisations/{org}/catalogues/{cat}/elements/{elem}/fields/{field}/calc/{index?} |
Calculation export |
| GET |
/api/organisations/{org}/catalogues/{cat}/elements/{elem}/fields/{field}/nested |
Nested indices export |
Authentication Requirements
- Public APIs: iCal calendar feeds (no auth)
- Sanctum Protected: Most SPA APIs require valid Sanctum token
- Web Session: Session management APIs use web session auth
- Policy Middleware: Organization access controlled via
policy:view,Organisation
- Permission Middleware: Fine-grained permissions via
hasPermission:
- Rate Limiting: Most APIs throttled, some exceptions for real-time features
Data Contracts
Core Domain Models
- Organisation: Multi-tenant root entity
- User: System users with org memberships
- Catalogue: Business catalogues with versioning
- Element: Units within catalogues (primer, strategy, custom, uploads, optts, graphics)
- Field: Data fields within elements with progress tracking
- Objective/Project/Task/Target (OPTT): Business planning entities
- Session: Scheduled events with guides/facilitators/convenors
Key Relationships
- User ↔ Organisation (many-to-many with roles/permissions)
- Organisation → Catalogue (one-to-many)
- Catalogue → Element (one-to-many)
- Element → Field (one-to-many with tabs)
- User → Field Progress (tracking completion)
- Organisation → OPTT entities (one-to-many)