🏢 Incubator API

Advanced Multi-Tenant Business Incubation Management Platform


v1.0.0 REST JSON API JWT Auth Multi-Tenant Full Audit Trail

Live at api-incubator.pretix.co.za

Getting Started

Base URL

https://api-incubator.pretix.co.za/api/v1

Authentication

All protected routes require a Bearer JWT token in the Authorization header:

Authorization: Bearer <your_access_token>

Response Format

{
  "status":  "success" | "error",
  "message": "Human readable message",
  "data":    { ... } | [ ... ],
  "pagination": {           // present on list endpoints
    "total": 100,
    "per_page": 20,
    "current_page": 1,
    "last_page": 5
  }
}

Query Parameters (list endpoints)

ParamDescriptionDefault
pagePage number1
per_pageItems per page (max 100)20
sortColumn to sort bycreated_at
orderASC or DESCDESC

Quick Start — Register a new Incubator

POST /api/v1/auth/register-tenant
Content-Type: application/json

{
  "tenant_name":  "My Incubator",
  "tenant_email": "admin@myincubator.co.za",
  "first_name":   "John",
  "last_name":    "Doe",
  "email":        "john@myincubator.co.za",
  "password":     "SecurePassword123!"
}

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "email":    "john@myincubator.co.za",
  "password": "SecurePassword123!"
}

Platform Modules

🏢 Tenants

Each incubator is a tenant. Full isolation of all data per tenant.

👥 Users & Roles

Multi-role RBAC with granular per-module permissions. Assign custom roles.

📅 Cohorts

Create and manage incubation programmes. Track start/end dates, status and businesses.

🏭 Businesses

Full business profiles, owner/assignee tracking, milestones and progress.

💰 Sponsors & Funders

Track sponsors, link them to cohorts or individual businesses with funding amounts.

📦 Resources

Custom resource types (laptops, grants, interns, loans). Assign and return with full history.

💳 Budgets

Create budgets with line items, approve them, track planned vs actual spend.

📋 Requests

Send structured requests to business owners/assignees. Track status, add comments.

📊 Reports

Dashboard, cohort reports, business reports, resource utilisation, budget variance.

🔍 Audit Trail

Every create/update/delete is logged with old/new values, user, IP and timestamp.

Authentication

MethodEndpointDescriptionAuth
POST/auth/register-tenantRegister a new incubator + admin user❌
POST/auth/loginLogin with email, password and tenant_id❌
POST/auth/refreshRefresh access token❌
POST/auth/forgot-passwordRequest password reset❌
POST/auth/reset-passwordReset password with token❌
GET/auth/meGet current user + permissions✅
PUT/auth/meUpdate own profile✅
PUT/auth/change-passwordChange own password✅
POST/auth/logoutLogout (revokes refresh token)✅

Tenants

MethodEndpointDescriptionPermission
GET/tenantsList all tenantstenants.view
POST/tenantsCreate tenanttenants.create
GET/tenants/{id}Get tenant + statstenants.view
PUT/tenants/{id}Update tenanttenants.update
DELETE/tenants/{id}Delete tenant (soft)tenants.delete

Users & Roles

MethodEndpointDescriptionPermission
GET/usersList usersusers.view
POST/usersCreate userusers.create
GET/users/{id}Get user + rolesusers.view
PUT/users/{id}Update userusers.update
DELETE/users/{id}Delete userusers.delete
POST/users/{id}/rolesAssign roleusers.manage_roles
DELETE/users/{id}/roles/{roleId}Remove roleusers.manage_roles
POST/users/{id}/reset-passwordAdmin reset passwordusers.update
GET/permissionsList all permissions grouped by moduleroles.view
GET/rolesList rolesroles.view
POST/rolesCreate role with permissionsroles.create
GET/roles/{id}Get role + permissionsroles.view
PUT/roles/{id}Update role + sync permissionsroles.update
DELETE/roles/{id}Delete custom roleroles.delete

Default System Roles

super_admin tenant_admin manager mentor business_owner assignee

Cohorts

MethodEndpointDescriptionPermission
GET/cohortsList cohorts (filter: status)cohorts.view
POST/cohortsCreate cohortcohorts.create
GET/cohorts/{id}Get cohort + business countcohorts.view
PUT/cohorts/{id}Update cohortcohorts.update
DELETE/cohorts/{id}Delete cohortcohorts.delete
GET/cohorts/{id}/businessesBusinesses in cohortcohorts.view
GET/cohorts/{id}/sponsorsSponsors linked to cohortcohorts.view

Businesses

MethodEndpointDescriptionPermission
GET/businessesList businesses (filter: cohort_id, status, sector)businesses.view
POST/businessesCreate businessbusinesses.create
GET/businesses/{id}Get business + owner + assignees + resource countbusinesses.view
PUT/businesses/{id}Update businessbusinesses.update
DELETE/businesses/{id}Delete businessbusinesses.delete
GET/businesses/{id}/assigneesList assigneesbusinesses.view
POST/businesses/{id}/assigneesAdd assigneebusinesses.manage_assignees
DELETE/businesses/{id}/assignees/{userId}Remove assigneebusinesses.manage_assignees
GET/businesses/{id}/milestonesList milestonesmilestones.view
POST/businesses/{id}/milestonesCreate milestonemilestones.manage
PUT/businesses/{id}/milestones/{milestoneId}Update milestone / progressmilestones.manage

Sponsors & Funders

MethodEndpointDescriptionPermission
GET/sponsorsList sponsorssponsors.view
POST/sponsorsCreate sponsor/fundersponsors.create
GET/sponsors/{id}Get sponsor + linked cohorts/businessessponsors.view
PUT/sponsors/{id}Update sponsorsponsors.update
DELETE/sponsors/{id}Delete sponsorsponsors.delete
POST/sponsors/{id}/cohortsLink sponsor to cohort (with amount)sponsors.update
DELETE/sponsors/{id}/cohorts/{cohortId}Unlink from cohortsponsors.update
POST/sponsors/{id}/businessesLink sponsor to businesssponsors.update
DELETE/sponsors/{id}/businesses/{businessId}Unlink from businesssponsors.update

Sponsor Types

sponsorfunderdonorinvestorgovernmentngoother

Resources

First create Resource Types (e.g. Laptop, Grant, Intern, Loan), then create Resources of that type and assign them to businesses.

MethodEndpointDescriptionPermission
GET/resource-typesList resource typesresources.view
POST/resource-typesCreate type (Laptop, Grant, etc.)resource_types.manage
PUT/resource-types/{id}Update typeresource_types.manage
DELETE/resource-types/{id}Delete typeresource_types.manage
GET/resourcesList all resources (filter: status, resource_type_id)resources.view
POST/resourcesAdd resource to inventoryresources.create
GET/resources/{id}Get resource + typeresources.view
PUT/resources/{id}Update resourceresources.update
DELETE/resources/{id}Delete resourceresources.delete
GET/resources/{id}/assignmentsHistory of assignmentsresources.view
POST/resources/{id}/assignAssign resource to business/userresources.assign
POST/resources/assignments/{assignmentId}/returnMark resource as returnedresources.assign

Resource Type Categories

physicalfinancialhumanserviceother

Budgets

MethodEndpointDescriptionPermission
GET/budgetsList budgets (filter: status, cohort_id, business_id)budgets.view
POST/budgetsCreate budgetbudgets.create
GET/budgets/{id}Get budget + line items + totalsbudgets.view
PUT/budgets/{id}Update budget (draft only)budgets.update
DELETE/budgets/{id}Delete budgetbudgets.delete
POST/budgets/{id}/approveApprove budgetbudgets.approve
POST/budgets/{id}/itemsAdd line itembudgets.update
PUT/budgets/{id}/items/{itemId}Update line item (actual spend)budgets.update
DELETE/budgets/{id}/items/{itemId}Remove line itembudgets.update

Requests

MethodEndpointDescriptionPermission
GET/requestsList requests (filter: status, priority, business_id, assigned_to)requests.view
POST/requestsCreate request to business/assigneerequests.create
GET/requests/{id}Get request + comments + relationsrequests.view
PUT/requests/{id}Update requestrequests.update
DELETE/requests/{id}Delete requestrequests.delete
POST/requests/{id}/statusUpdate status (with response text)requests.respond
GET/requests/{id}/commentsGet comments threadrequests.view
POST/requests/{id}/commentsAdd comment (internal flag supported)requests.respond

Request Statuses

pendingacknowledgedin_progresscompletedrejected

Reports

MethodEndpointDescriptionPermission
GET/reports/dashboardOverall KPI dashboard for the tenantreports.view
GET/reports/cohorts/{id}Full cohort report (businesses, sponsors, budgets, resources, milestones)reports.view
GET/reports/businesses/{id}Full business report (resources assigned, milestones, requests, budgets)reports.view
GET/reports/resourcesResource utilisation report by type/categoryreports.view
GET/reports/budgetsBudget variance report (planned vs actual)reports.view

Audit Trail

Every create, update, delete, login, logout, password reset and permission denial is automatically recorded with: who, what, when, from where, old values and new values.

MethodEndpointDescriptionPermission
GET/audit-logsFull audit log (filter: action, module, entity_type, user_id, from, to)audit.view
GET/audit-logs/{entityType}/{entityId}Audit trail for a specific entityaudit.view

Audit Log Entry Structure

{
  "id":             123,
  "tenant_id":      "uuid",
  "user_id":        "uuid",
  "user_email":     "admin@example.com",
  "action":         "update",
  "module":         "businesses",
  "entity_type":    "business",
  "entity_id":      "uuid",
  "description":    "Business updated: Acme Corp",
  "old_values":     { "status": "active", "employees_count": 3 },
  "new_values":     { "status": "graduated", "employees_count": 3 },
  "ip_address":     "196.25.1.100",
  "user_agent":     "Mozilla/5.0 ...",
  "request_method": "PUT",
  "request_path":   "/api/v1/businesses/uuid",
  "created_at":     "2026-03-05T14:32:00+02:00"
}