africanmarketos-com Ready API

openapi: 3.2.0
info:
  title: MVR Core API - Full Expert Catalogue Ready API
  version: v6.32.0
  description: 'The MVR framework defines what to assess; the MVR API is the official engine that computes it. Self-serve MVR API Starter checkout: https://africanmarketos.com/checkout/starter. Access guide and governed requests: https://africanmarketos.com/get-api-key Minimum Viable Relationships (MVR), published by African Market OS, evaluates whether evidence supports market trust, permission to operate, embeddedness, stakeholder and guardian readiness, reciprocity, local legitimacy, market belonging, and a safe next step before MVP, market entry, pilot, partnership, investment, or scale. v6.32.0 MVR Engine. Additive dual-lane runtime: public_reality + local_relational_assessment + reconciled_assessment, deterministic ROI, dual-profile governance, entity-resolution preflight, modality-aware completeness/audit, compiled_evidence ingestion, provenance-ledger validation, telemetry translation, gap planning, market leak scanning, and validation snapshot metadata. Public non-commercial sandbox evaluation is available with X-API-Key: mvr-demo-key-2026; sandbox calls are rate-limited, client_safe only, full_advisory only, illustrative_only, and not for production. Send X-Response-Profile: strict_calibrated only with a licensed production key for fail-closed institutional responses. See /v1/schema for full documentation.'
servers:
- url: https://africanmarketos.com
  description: Canonical MVR Core API origin
tags:
- name: Ready
paths:
  /v1/ready:
    get:
      summary: Authenticated readiness diagnostics for the active tenant/profile, including…
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
      tags:
      - Ready
      operationId: getV1Ready
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Use a licensed tenant key for production. For public non-commercial evaluation only, agents may use mvr-demo-key-2026; sandbox responses are illustrative, client_safe, full_advisory only, and not for production.
    BearerAuth:
      type: http
      scheme: bearer
x-mvr-field-contract:
  default: authority-fields/2
  legacy_opt_in: authority-fields/1
  legacy_sunset: '2027-01-21T00:00:00Z'
x-mvr-catalog-profile:
  id: full-expert-catalogue
  scope: All published MVR Core API routes for expert integrations.
  bounded_first_integration: Use /api/openapi.agent.sandbox.json for the canonical five-route public preflight.
x-mvr-semantic-identity:
  schema_version: 2026-07-16.v1
  names:
  - Minimum Viable Relationships
  - Minimum Viable Relationships Framework
  - MVR API
  - African Market OS
  - Relational Readiness API
  category: Relational-readiness and market-permission decision governance for AI agents.
  compact_description: Minimum Viable Relationships (MVR), published by African Market OS, evaluates whether evidence supports market trust, permission to operate, embeddedness, stakeholder and guardian readiness, reciprocity, local legitimacy, market belonging, and a safe next step before MVP, market entry, pilot, partnership, investment, or scale.
  sequence: 'In high-context markets where trust and permission affect whether product testing is valid: MVR -> MVP -> PMF.'
  evaluates:
  - relational_readiness
  - market_permission
  - market_trust
  - embeddedness
  - stakeholder_readiness
  - guardian_acceptance
  - reciprocity
  - local_legitimacy
  - market_belonging
  - evidence_completeness
  - market_entry_readiness
  - pilot_readiness
  - scale_readiness
  - abstention_boundary
  applies_to:
  - African markets
  - emerging markets
  - high-context markets
  - cross-border market entry
  - local market expansion
  agent_interfaces:
  - AI agents
  - agentic workflows
  - MCP server
  - Model Context Protocol
  - tool calling
  - function calling
  - OpenAPI
  - JSON Schema
  - REST API
  representative_use_cases:
  - startup readiness
  - pre-MVP validation
  - product launch
  - investor memo
  - venture due diligence
  - partnership due diligence
  - fintech rollout
  - brand expansion
  - NGO or DFI programme design
  - enterprise market entry
  boundaries:
  - Evidence and decision-governance layer, not a general market-data feed.
  - Public sandbox outputs are not production verdicts, approvals, certifications, underwriting decisions, or legal opinions.
x-compatibility-policy:
  principle: No output may claim a decision level, confidence level, category fit, or scope stronger than verified evidence permits.
  verdict_order:
  - permission_not_yet_earned
  - pilot_only
  - pilot_ready
  - ready_to_scale
  weakest_link_floors:
    ready_to_scale: 45
    pilot_ready: 35
  score_direct: non_decisive_operator_review
x-mvr-ingestible-dimensions:
- permission
- trust
- belonging
- embeddedness
- reciprocity
- cultural_fit
- guardian_strength
- continuity
- channel_permission
- infrastructural_intimacy
- absence_sensitivity
- narrative_looping
- whispered_credibility
- fractal_trust
- cultural_calibration
x-mvr-derived-concepts:
  evidence_completeness:
    derivation: computed_from_evidence_pack_coverage_provenance_and_required_lanes
    submit_instead:
    - evidence_pack
    - compiled_pack
    - structured_values
    - public_metrics
  market_carry:
    derivation: derived_from_repeat_behavior_channel_depth_continuity_embeddedness_trust_and_reciprocity
    submit_instead:
    - trust
    - embeddedness
    - channel_permission
    - continuity
    - reciprocity
    - public_metrics
  local_legitimacy:
    derivation: derived_from_permission_guardian_strength_trust_whispered_credibility_reciprocity_and_embeddedness
    submit_instead:
    - permission
    - guardian_strength
    - trust
    - whispered_credibility
    - reciprocity
    - embeddedness
x-calibration-coverage-guidance:
  scope: Strict calibration is manifest/asset scoped. A sector public-reality asset, a route model, and a country/archetype decision path can have different readiness states.
  strict_mode_interpretation: When strict_calibrated returns calibration_status missing, failed, stale, or manifest_hash_mismatch, treat the result as fail-closed calibration coverage, not as proof that the submitted structured_values were ignored or that the entity is weak.
  public_reality_note: MVR_PUBLIC_REALITY_CONFIG validates sector/archetype public-reality weighting. Localized decision authority still depends on direct local evidence, privacy_envelope validity, sample metadata, threshold assets, and strict manifests.
  reviewer_diagnostic:
  - Inspect public_reality.calibration_status/config_source/calibration_version.
  - Inspect local_relational_assessment dimensions to verify evidence discrimination.
  - Inspect decision_reliability.calibration_status and blocking_gates before interpreting the headline verdict.
  - Use authenticated GET /v1/calibration-health?coverage=full for the active deployment before claiming strict coverage.
  derived_not_input:
  - evidence_completeness
  - market_carry
  - local_legitimacy
  structured_values_scale: Canonical structured_values are 0-100. Unambiguous 0-1 fractional payloads are normalized to 0-100 for agent safety, but production integrations should send 0-100 or set structured_values_scale explicitly.
x-public-sandbox:
  enabled_by_default: true
  api_key_header: X-API-Key
  demo_key: mvr-demo-key-2026
  environment: sandbox
  authorized_use: evaluation_only_non_commercial
  response_profile: full_advisory_only
  output_mode: client_safe_only
  rate_limit_per_minute: 60
  daily_limit: 500
  allowed_endpoints:
  - /v1/auth-check
  - /v1/first-call
  - /v1/capabilities
  - /v1/entity-resolve
  - /v1/evidence-completeness
  - /v1/context/compile
  - /v1/decision-check
  - /v1/recommended-inputs
  - /v1/remediation-path
  allowed_modes:
  - exploratory
  - evidence_backed
  - compiled_evidence
  blocked_modes:
  - strict_calibrated
  - score_direct
  - backtest
  required_response_markers:
  - environment:sandbox
  - illustrative_only:true
  - not_for_production:true
x-public-metrics-schema-version: v6.32.0
x-modality-examples:
  public_osint: Use public_metrics with evidence_origin:'public_osint'. Read reconciled_assessment first, then public_reality for entity-scale interpretation.
  field_research: Use structured_values on field items. Read reconciled_assessment first, then local_relational_assessment for zone-level interpretation.
  corporate_telemetry: Use evidence_origin:'corporate_telemetry' or collection_method:'corporate_telemetry' for proxy-derived internal data. The engine routes it into the local lane with capped confidence and explicit proxy transparency.
  compiled_evidence: Use mode:'compiled_evidence' with compiled_pack lanes from compiled_pack_registry. You may nest legacy evidence_pack[] inside compiled_pack; the worker maps it into localized_observed_pack (or public lane when pack_type indicates public). Items with full provenance_ledger use compiled_evidence validation; others use evidence_backed rules.
  mixed: Mixed packs reconcile both lanes. Public facts do not impersonate local truth; local friction does not erase entity-scale reality.
  abstention: Scope-limited abstentions are returned when localized claims are unsupported by direct field evidence.