The Two-API Model
BCMLogic Next exposes two distinct APIs because they solve fundamentally different problems:
- Core API handles transactional, structured, audit-bound operations. It is the system of record. It must be deterministic, fast, and traceable.
- Intelligence Service handles AI-driven operations: document analysis, report generation, semantic search, recommendations. It is non-deterministic, latency-tolerant, and stateless with respect to business state.
Mixing these concerns in one API leads to poor developer experience, unclear SLAs, and unreliable audit trails. Separating them lets each evolve at its own pace with appropriate guarantees.
Decision Rule
If the operation creates, modifies, retrieves, or audits a business record — use Core API. If the operation generates, analyses, summarises, or reasons over content — use Intelligence Service.
When in doubt, apply this rule before reading further.
Quick Reference
| Use case | API | Endpoint |
|---|---|---|
| Create a risk in the register | Core | POST /v1/core/risks |
| List vendors by status | Core | GET /v1/core/vendors?status=active |
| Upload a vendor policy document | Core | POST /v1/core/documents |
| Retrieve an audit trail entry | Core | GET /v1/core/audit/{id} |
| Generate a Business Impact Analysis report | Intelligence | POST /v1/ai/reports/bia |
| Ask a question about uploaded documents | Intelligence | POST /v1/ai/chat |
| Summarise a vendor questionnaire | Intelligence | POST /v1/ai/summarize |
| Search semantically across the knowledge base | Intelligence | POST /v1/ai/search |
What Each API Guarantees
| Guarantee | Core API | Intelligence Service |
|---|---|---|
| Strong consistency | Yes — transactional writes | No — eventual; embeddings may lag uploads by ~30–60 s |
| Deterministic outputs | Yes | No — LLM-driven; same input may yield different outputs |
| Latency p95 | < 500 ms typical | 2–30 s for generation; sub-second for search |
| Idempotency keys | Required for writes | Optional but recommended for generation requests |
| Audit trail | Every mutation logged | Every generation logged with prompt, model, citations |
| Streaming responses | No | Yes — Server-Sent Events for generation endpoints |
What Core and Intelligence Share
Both APIs share:
- The same API Gateway — single base URL, single authentication flow.
- The same OAuth 2.0 / OIDC authentication and bearer token format.
- The same tenant model — tenant resolved from the token, never from the URL.
- The same error envelope — see Cross-cutting Concerns.
- The same pagination conventions — cursor-based, see Cross-cutting Concerns.
From a client perspective, "which API am I calling" is a routing detail visible only in the URL prefix. The integration patterns are uniform.
Further Reading
- Core API — full reference for modules, resource conventions, and mutations.
- Intelligence Service — endpoint families, knowledge sources, citations, and streaming.