APIs

Stable API surfaces for Fund Analyst Intelligence: funds, cycles, artefacts, exceptions, deltas, reports, alerts, and policy management.

APIs

Fund Analyst Intelligence should expose a small number of stable, production-safe API surfaces.
APIs must preserve evidence links, workflow states, and reproducibility.
Contracts must be versioned and predictable.

This page describes the conceptual API design.
It is not tied to a specific framework.
It is intended to guide implementation and integration.

API principles

Contract stability

Breaking changes must be rare and versioned.
Clients should not depend on internal implementation details.
Schemas should be explicit and documented.

Evidence-first payloads

Every key claim and change should include evidence references.
Evidence pointers are part of the contract.
Downstream systems must not lose provenance.

Workflow-aware operations

Draft, review, approved, and published are enforced states.
APIs must respect and expose these states.
Publication must be gated by approval.

Deterministic and reproducible

Responses should include identifiers for cycles, snapshots, rulesets, and policies.
This enables audits and report reproducibility.
It also supports safe reruns and debugging.

Authentication and authorisation

APIs should support:

  • strong authentication
  • role-based authorisation
  • portfolio-scoped access
  • auditable access logs

A caller should only see funds within its allowed scope.
Administrative endpoints should be tightly restricted.

Core resource groups

1. Funds

Purpose

Access canonical fund records and the current validated state.

Typical operations

  • list funds by portfolio/tag/filter
  • get fund profile summary
  • get latest snapshot and key fields
  • search funds by identifier

Key response properties

  • fund_id (stable internal id)
  • external identifiers (ISIN/share class ids)
  • status and tags
  • last validated cycle reference
  • link to latest snapshot

2. Cycles

Purpose

Track monthly validation runs and their workflow state.

Typical operations

  • list cycles for a fund
  • get cycle status and milestones
  • get cycle input inventory summary
  • get cycle outputs registry (reports/evidence packs)

Key response properties

  • cycle_id, timestamps
  • state (draft/review/approved/published/failed)
  • ruleset_id, materiality_id, source_policy_id
  • operator/reviewer assignments
  • reproducibility pointer to snapshot updates

Notes

Cycle creation and transitions may be restricted.
State transitions should be auditable.

3. Artefacts

Purpose

Manage source documents and online source records.

Typical operations

  • list artefacts for a fund or cycle
  • fetch artefact metadata and version links
  • upload/register artefact (operator/admin)
  • retrieve evidence pointers for claims and deltas

Key response properties

  • artefact_id, version, supersedes_artefact_id
  • source origin and timestamps
  • access scope and retention markers
  • storage pointer (never leak raw storage secrets)

Notes

Artefacts should be immutable after registration.
Access is sensitive and must be controlled.

4. Fields and claims

Purpose

Expose structured values and their evidence mapping.

Typical operations

  • get fund field set for a cycle or snapshot
  • get claims with evidence references
  • retrieve field-to-evidence mappings

Key response properties

  • typed field values
  • evidence references (artefact + location)
  • support/conflict/missing/stale states
  • override metadata and reviewer notes

5. Validation results and exceptions

Purpose

Expose quality signals and actionable issues.

Typical operations

  • list exceptions for a cycle (with filters)
  • get exception details and linked artefacts/deltas
  • update exception status (resolve, monitor, escalate)
  • assign owners and follow-up SLAs (role-restricted)

Key response properties

  • severity, category, status
  • recommended actions
  • linked evidence references
  • decision notes and closure metadata

Notes

Exception updates must be logged with actor and timestamp.

6. Deltas (change log)

Purpose

Expose structured changes between snapshots.

Typical operations

  • list deltas for a cycle
  • list deltas over a period (for quarterly synthesis)
  • retrieve delta evidence references and materiality inputs

Key response properties

  • typed old/new values
  • category tags
  • magnitude and direction
  • evidence references
  • materiality scoring fields

7. Reports and evidence packs

Purpose

Provide access to generated outputs.

Typical operations

  • list reports for a cycle
  • fetch report metadata and location
  • retrieve evidence pack reference and summary
  • verify approval/published status

Key response properties

  • report_id, report_type, template_version
  • generation timestamp
  • approval stamp reference
  • link to underlying cycle record for reproducibility

Notes Report access must respect portfolio and role permissions.

8. Alerts

Purpose
Expose escalation events for material changes and breaches.

Typical operations

  • list alerts by portfolio and severity
  • get alert payload and evidence links
  • mark alert as acknowledged/resolved
  • retrieve alert history per fund

Key response properties

  • alert type and severity
  • one-line summary
  • recommended action
  • evidence references
  • ownership and closure state

9. Policies (admin)

Purpose

Manage governance parameters as versioned policies.

Typical operations

  • list and retrieve versions of:
    • source policy
    • validation ruleset
    • materiality policy
  • activate a new policy version (controlled)
  • diff policy versions (optional)

Key response properties

  • policy ids and version metadata
  • effective date
  • change notes
  • scope applicability (portfolio or global)

Notes

Policy changes should be auditable and approvals may be required.

Error handling and observability

APIs should return stable error codes and include:

  • request_id for tracing
  • cycle_id and fund_id where relevant
  • explicit error classification (auth, validation, not found, conflict, rate limit)

This supports production debugging and incident response.

Definition of done

The API layer is production-grade when:

  • contracts are versioned and documented
  • access control is role-based and portfolio-scoped
  • workflow states are enforced by endpoints
  • all key objects preserve evidence references
  • outputs can be traced to cycle records
  • logs support operational diagnosis and audit

This is what makes integration safe and scalable.