Skip to main content

Intelligence Service

Base URL: https://api.bcmlogic.com/v1/ai
Style: RESTful, JSON. Generation endpoints support streaming via Server-Sent Events (Accept: text/event-stream).
Purpose: AI-driven operations over tenant data and BCMLogic's curated regulatory knowledge base.

For guidance on when to call Intelligence Service versus Core API, see The Two-API Model.

Endpoint Families​

FamilyPathWhat it does
Chat/v1/ai/chatConversational interface; can reference uploaded documents and operational data.
Reports/v1/ai/reports/{type}Generates structured reports — BIA, risk register, vendor analysis.
Search/v1/ai/searchSemantic + keyword hybrid search across documents and regulations.
Summarise/v1/ai/summarizeSummarisation of a document or a collection.
Analyse/v1/ai/analyze/{kind}Specialised analysers — questionnaire scoring, control mapping, and others.

Knowledge Sources​

When you call Intelligence Service, three sources of context may be combined:

  1. Tenant documents. Files your organisation uploaded through Core API (POST /v1/core/documents). Each document is parsed, chunked, embedded, and indexed in a tenant-scoped vector store. Indexing is asynchronous and typically completes within 30–60 seconds of upload.

  2. Regulatory knowledge base. A versioned, curated corpus maintained by BCMLogic: DORA, NIS2, ISO 22301, ISO 31000, EBA Guidelines, ENISA publications. Shared across all tenants, read-only. Pin a specific version per request to ensure reproducibility. See ADR-008.

  3. Operational data. Structured records in Core API. Intelligence Service retrieves them at request time through internal tool calls — you do not need to include them in the request body.

Specify which sources to use through the context parameter on each request.

Request Shape​

{
  "context": {
    "tenant_documents": { "ids": ["doc_01HQ...", "doc_01HR..."] },
    "regulatory_kb": { "frameworks": ["DORA", "NIS2"], "version": "2026-Q1" },
    "operational_data": { "include": ["risks", "vendors"] }
  },
  "parameters": {
    "process_id": "prc_01HQ...",
    "output_format": "markdown"
  },
  "options": {
    "stream": false,
    "include_citations": true,
    "max_latency_seconds": 30
  }
}

Example — generate a BIA report​

curl -X POST https://api.bcmlogic.com/v1/ai/reports/bia \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002" \
  -d '{
    "context": {
      "regulatory_kb": { "frameworks": ["ISO 22301"], "version": "2026-Q1" },
      "operational_data": { "include": ["processes"] }
    },
    "parameters": { "process_id": "prc_01HQ8K3MNPQRS", "output_format": "markdown" },
    "options": { "stream": false, "include_citations": true }
  }'
const response = await fetch('https://api.bcmlogic.com/v1/ai/reports/bia', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    context: {
      regulatory_kb: { frameworks: ['ISO 22301'], version: '2026-Q1' },
      operational_data: { include: ['processes'] },
    },
    parameters: { process_id: 'prc_01HQ8K3MNPQRS', output_format: 'markdown' },
    options: { stream: false, include_citations: true },
  }),
});

Response Shape (Non-streaming)​

{
  "id": "gen_01HQ...",
  "type": "bia_report",
  "content": {
    "markdown": "...",
    "structured": { }
  },
  "citations": [
    {
      "ref_id": "c1",
      "source_type": "regulatory_kb",
      "source_id": "DORA:Article:11",
      "version": "2026-Q1",
      "excerpt": "..."
    },
    {
      "ref_id": "c2",
      "source_type": "tenant_document",
      "source_id": "doc_01HQ...",
      "chunk": "..."
    }
  ],
  "meta": {
    "model": "claude-opus-4-6",
    "tokens": { "input": 18432, "output": 2104 },
    "latency_ms": 7820,
    "generated_at": "2026-05-15T10:30:00Z"
  }
}

Streaming Responses​

Request Accept: text/event-stream on generation endpoints for interactive use cases. The service emits incremental tokens, tool invocations, and citation events. The final event always includes the complete meta block and full citation list.

const response = await fetch('https://api.bcmlogic.com/v1/ai/reports/bia', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify({ /* same body as above */ }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Citations Are Part of the Contract​

Every AI-generated response includes citations linking back to the exact source — a chunk of a tenant document, a paragraph of a regulation, or a row from operational data. Citations are part of the API contract, not an optional feature.

If you build user-facing flows on Intelligence Service, render citations alongside generated content. This is both a quality signal and a requirement for clients operating under DORA Article 28 (AI-assisted decision-making). See ADR-004.

What Intelligence Service Does Not Do​

  • Does not modify business state. To create or update a record, call Core API. Intelligence Service can recommend changes; the client or user decides.
  • Does not return raw model output without provenance. There is always a citations block and a meta.model field.
  • Does not accept arbitrary file uploads. Documents must be uploaded through Core API first (POST /v1/core/documents), then their document_id is referenced in the context parameter.