Live demoBook a demo
Developer portal

Build on Blue Oceans Business OS

Tenant-scoped REST API · HMAC-signed webhooks · OpenAPI 3.1 · sandbox with synthetic data

Download OpenAPI JSONRequest a live key

API reference

Rendered from the same OpenAPI 3.1 document served at /api/v1/openapi.json. Import it into Postman, Insomnia or your code generator.

Platform

GET/api/v1/healthpublic

Health check

Example request

curl https://blueoceansapproach.co.za/api/v1/health

Example response (200)

{
  "status": "ok",
  "version": "1.0.0",
  "region": "af-south-1 (target)"
}

Responses: 200 Service healthy

GET/api/v1/cataloguepublic

Public product catalogue

Modules, packages and list prices (ZAR, excl. VAT).

Example request

curl https://blueoceansapproach.co.za/api/v1/catalogue

Example response (200)

{
  "data": {
    "currency": "ZAR",
    "modules": [
      {
        "slug": "peopleos",
        "name": "PeopleOS (IWPMS)",
        "pricing": {
          "sme": 999,
          "growth": 2999,
          "enterprise": 15000
        }
      }
    ],
    "tiers": [
      {
        "slug": "growth",
        "name": "Growth",
        "price": 3999
      }
    ]
  },
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true
  }
}

Responses: 200 Catalogue

GET/api/v1/openapi.jsonpublic

This OpenAPI document

Example request

curl https://blueoceansapproach.co.za/api/v1/openapi.json

Responses: 200 OpenAPI 3.1 JSON

PeopleOS

GET/api/v1/workersread:workers

List workers

Example request

curl https://blueoceansapproach.co.za/api/v1/workers \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab"

Example response (200)

{
  "data": [
    {
      "id": "w-07",
      "name": "Ayanda Khumalo",
      "role": "Site Supervisor",
      "manager": "w-02",
      "sowVersion": "v1",
      "readiness": "ready"
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true
  }
}

Responses: 200 Workers in the key's tenant · 401 Invalid key

GET/api/v1/deliverablesread:deliverables

List deliverables

ParameterInRequiredDescription
statusqueryNoopen | submitted | accepted | returned — e.g. submitted

Example request

curl https://blueoceansapproach.co.za/api/v1/deliverables \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab"

Example response (200)

{
  "data": [
    {
      "id": "DLV-1042",
      "workerId": "w-07",
      "title": "Monthly site audit",
      "due": "2026-10-24",
      "status": "submitted",
      "evidenceCount": 2
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true
  }
}

Responses: 200 Deliverables

POST/api/v1/deliverables/{id}/evidencewrite:evidence

Attach evidence metadata to a deliverable

Registers evidence (hash + metadata). The file itself is uploaded to a short-lived signed storage URL in production. Requires an Idempotency-Key header; replays return the original response.

ParameterInRequiredDescription
idpathYesDeliverable ID — e.g. DLV-1043
Idempotency-KeyheaderYesUnique per logical request (UUID recommended) — e.g. 6f1c2a9e-0b7d-4e55-9a51-2f7c9c1d1b10

Example request

curl -X POST https://blueoceansapproach.co.za/api/v1/deliverables/DLV-1043/evidence \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab" \
  -H "Idempotency-Key: <uuid>" \
  -H "Content-Type: application/json" \
  -d '{"filename":"stock-count-sept.pdf","sha256":"9b74c9897bac770ffc029102a200c5de9b74c9897bac770ffc029102a200c5de","size":182044,"mime":"application/pdf","note":"Signed by site manager"}'

Example response (201)

{
  "data": {
    "id": "EVD-7c1e2a",
    "deliverableId": "DLV-1043",
    "filename": "stock-count-sept.pdf",
    "status": "pending-review"
  },
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true
  }
}

Responses: 201 Evidence registered · 400 Validation error · 404 Deliverable not found in this tenant · 409 Idempotency key reused with a different body · 428 Idempotency-Key header missing

GET/api/v1/kpisread:kpis

List KPI results

ParameterInRequiredDescription
workerIdqueryNoFilter by worker — e.g. w-07

Example request

curl https://blueoceansapproach.co.za/api/v1/kpis \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab"

Example response (200)

{
  "data": [
    {
      "id": "K-01",
      "workerId": "w-07",
      "name": "Site checks completed on time",
      "target": 95,
      "actual": 97,
      "unit": "%",
      "weight": 40
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true,
    "weightedScore": 96.1
  }
}

Responses: 200 KPI results with weighted score

ComplianceOS

GET/api/v1/compliance/obligationsread:compliance

List compliance obligations

Example request

curl https://blueoceansapproach.co.za/api/v1/compliance/obligations \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab"

Example response (200)

{
  "data": [
    {
      "id": "OB-03",
      "name": "B-BBEE affidavit renewal",
      "owner": "CEO",
      "dueDate": "2026-10-28",
      "status": "due-soon"
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true
  }
}

Responses: 200 Obligations with status

Sales & Leads

POST/api/v1/leadswrite:leads

Create a lead

POPIA consent must be true. Stored in the platform CRM.

Example request

curl -X POST https://blueoceansapproach.co.za/api/v1/leads \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sample Person","email":"owner@example.co.za","company":"Sample Co (fictional)","interest":["peopleos"],"consent":true}'

Example response (201)

{
  "data": {
    "id": "lead_1a2b3c4d",
    "stage": "New"
  },
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true
  }
}

Responses: 201 Lead created · 400 Validation error

Provisioning

POST/api/v1/tenantstenant:provision

Request a new tenant (24-hour activation)

Partner/admin keys only (scope tenant:provision). The public sandbox key returns 403 by design.

Example request

curl -X POST https://blueoceansapproach.co.za/api/v1/tenants \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab" \
  -H "Content-Type: application/json" \
  -d '{"company":"Sample Courier (fictional)","adminEmail":"admin@example.co.za","plan":"growth","modules":["serviceos","peopleos"],"users":12,"country":"ZA"}'

Example response (202)

{
  "data": {
    "job": "eyJ…sig",
    "status": "provisioning",
    "statusUrl": "/admin/provisioning/eyJ…sig"
  },
  "meta": {
    "apiVersion": "v1",
    "tenant": "kusasa",
    "environment": "test",
    "generatedAt": "2026-10-20T08:00:00Z",
    "syntheticData": true
  }
}

Responses: 202 Provisioning started · 403 Key lacks tenant:provision

Webhooks

GET/api/v1/webhooks/eventspublic

Webhook event catalogue

Example request

curl https://blueoceansapproach.co.za/api/v1/webhooks/events

Responses: 200 Event types with example payloads

POST/api/v1/webhooks/verifypublic

Verify a webhook signature (sandbox helper)

Never send production secrets to this helper — verify in your own code.

Example request

curl -X POST https://blueoceansapproach.co.za/api/v1/webhooks/verify \
  -H "Content-Type: application/json" \
  -d '{"secret":"whsec_test_example","payload":"{\"id\":\"evt_01\"}","signature":"t=1760947200,v1=…"}'

Example response (200)

{
  "ok": false,
  "reason": "expired"
}

Responses: 200 Verification result