Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: MVR Core API - Full Expert Catalogue Commercial Handshake…
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: Commercial Handshake
paths:
/v1/commercial-handshake:
post:
summary: Submit a user-approved non-confidential commercial brief to African Market OS
description: Public agent-native commercial intake. Requires explicit user approval, Idempotency-Key, confirmation that the brief is non-confidential, and separate consent before contact details are stored. The returned SHA-256 receipt proves submission integrity only; it is not an MVR verdict, evidence validation, approval, certification, or prediction.
security: []
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
minLength: 12
maxLength: 120
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- use_case
- organization_type
- decision_stage
- brief
- user_confirmed_submission
- non_confidential_brief
properties:
idempotency_key:
type: string
minLength: 12
maxLength: 120
description: Caller-generated retry key. Reuse it only for an identical submission.
use_case:
type: string
enum:
- institutional_shadow_review
- market_entry_preflight
- retail_expansion_readiness
- fintech_corridor_diligence
- investor_relational_due_diligence
- partner_due_diligence
- brand_localization
- procurement_tender_readiness
- ngo_dfi_program_readiness
- embeddedness_audit
- founder_decision_readiness_pilot
- mvr_api_integration
- mvr_examiner
- speaking_and_masterclasses
- research_and_data_partnership
description: The bounded decision or engagement category the user explicitly wants African Market OS to review.
organization_type:
type: string
enum:
- founder_or_venture
- investor_or_fund
- bank_or_insurer
- corporate_or_multinational
- ngo_or_dfi
- government_or_public_agency
- advisor_or_consultancy
- ai_agent_or_platform
- research_or_academic
- other
description: The submitting organization category; this controls routing only and is not an eligibility verdict.
country:
type: string
description: Country or corridor relevant to the proposed decision.
sector:
type: string
description: Sector or operating context when known.
decision_stage:
type: string
enum:
- exploring
- pre_entry
- pilot_design
- pilot_running
- scale_review
- diligence
- procurement
- integration
- other
description: Current stage of the decision or engagement.
timeline:
type: string
description: Non-confidential timing or deadline for the decision.
brief:
type: string
minLength: 20
maxLength: 1500
description: User-approved non-confidential description of the decision that needs review.
source_agent:
type: string
description: Optional host or agent name for aggregate channel measurement.
acquisition_source:
type: string
pattern: ^[a-z0-9][a-z0-9_:-]{0,79}$
description: Optional bounded, non-PII source label carried from the referring AMOS page or approved agent route. This is attribution context, not proof of identity.
offer_id:
type: string
enum:
- mvr_api_starter
- founder_embeddedness_audit
- venture_embeddedness_audit
- portfolio_embeddedness_audit
- venture_market_entry_review
- retail_partner_diligence
- fintech_corridor_preflight
- institutional_shadow_review
- mvr_examiner
- speaking_and_masterclasses
- founder_decision_readiness_pilot
- research_and_data_partnership
- african_startups_playbook
description: Stable offer identifier from /.well-known/mvr-offer-registry.json. The server derives it from use_case when omitted.
acquisition_id:
type: string
format: uuid
description: Optional random, non-PII journey identifier used to link discovery with a consented submission.
intent_id:
type: string
format: uuid
description: Optional random, non-PII identifier for this specific commercial intent.
user_confirmed_submission:
type: boolean
const: true
description: Must be true only after the user reviews and explicitly approves the exact brief.
non_confidential_brief:
type: boolean
const: true
description: Must be true only after confirming that the brief contains no confidential evidence, credentials, personal case records, or regulated data.
consent_to_contact:
type: boolean
description: Required and true when any contact details are supplied.
contact:
type: object
description: Optional contact details supplied by the user with separate consent.
properties:
name:
type: string
description: User-approved contact name.
email:
type: string
format: email
description: User-approved reply email.
phone:
type: string
description: User-approved reply phone number.
additionalProperties: false
additionalProperties: false
responses:
'202':
description: Commercial brief received
'400':
description: Consent or validation error
'409':
description: Idempotency or offer mismatch
'429':
description: Rate limited
'503':
description: Private storage unavailable
tags:
- Commercial Handshake
operationId: postV1CommercialHandshake
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.