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 Outcome Feedback 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: Outcome Feedback
paths:
/v1/outcome-feedback:
post:
summary: Compatibility route for a consented observation tied to an existing prospective…
description: Compatibility entrypoint for submitting a consented outcome observation against an existing prospective outcome-ledger enrollment.
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
minLength: 8
maxLength: 128
description: Required when x-mvr-idempotency-policy matches the actual request. Reuse the original key and request when reconciling a retry.
x-mvr-registry-route: /v1/outcome-feedback
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
x-mvr-validator-contract:
name: validateOutcomeFeedback
status: registry_metadata_enforced_by_shared_gateway
x-mvr-idempotency-key-required: true
x-mvr-idempotency-policy:
mode: required
x-mvr-access:
plans:
- ENTERPRISE
required_roles_any: []
output_modes:
- internal_full
- client_safe
break_glass_allowed: false
security:
- ApiKeyAuth: []
- BearerAuth: []
responses:
'200':
description: Successful response
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
'400':
description: Bad request
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/RequestErrorResponse'
'403':
description: Forbidden
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/RequestErrorResponse'
'404':
description: Not found
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/RequestErrorResponse'
'409':
description: Conflict. For idempotent operations, reconcile IDEMPOTENCY_CONTEXT_MISMATCH or IDEMPOTENCY_REQUEST_MISMATCH without changing the original key to bypass the conflict.
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/RequestErrorResponse'
'422':
description: Validation or calibration failure
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/RequestErrorResponse'
'429':
description: Rate or compute limit exceeded
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/RequestErrorResponse'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
output_mode:
type: string
enum:
- internal_full
- client_safe
response_profile:
type: string
enum:
- full_advisory
- strict_calibrated
action:
type: string
enum:
- get_followup_offer
- issue_consent_token
- decline_followup
- enroll
- record_outcome
- get
- list
- metrics
- withdraw
decision_check_id:
type: string
pattern: ^DCHK-[A-Za-z0-9-]{1,100}$
description: Server-issued decision ID, allowed only for get_followup_offer. Caller-supplied eligibility or verdict fields cannot establish eligibility.
decision_reference_hash:
type: string
pattern: ^[A-Fa-f0-9]{64}$
subject_reference:
type: string
description: Internal non-contact case reference. It is server-keyed and never persisted raw.
entity_reference:
type: string
description: Alias of subject_reference.
horizon_months:
type: array
items:
type: integer
enum:
- 6
- 12
- 18
minItems: 3
maxItems: 3
uniqueItems: true
description: The active first-cohort contract requires exactly [6, 12, 18].
consent_attestation:
type: object
additionalProperties: false
properties:
confirmed_by_authorized_human:
type: boolean
const: true
consent_version:
type: string
const: mvr-outcome-consent@2026-07-24.2
followup_owner_role:
type: string
enum:
- decision_owner
- authorized_delegate
- organizational_reviewer
recorded_at:
type: string
format: date-time
record_reference_hash:
type: string
pattern: ^[A-Fa-f0-9]{64}$
required:
- confirmed_by_authorized_human
- consent_version
- followup_owner_role
- recorded_at
- record_reference_hash
consent_token:
type: string
writeOnly: true
description: Short-lived, one-time operator-issued token. Never persist or log it.
decline_reason_code:
type: string
enum:
- not_provided
- owner_declined
- owner_unavailable
- followup_not_feasible
predicted_verdict:
type: string
enum:
- permission_not_yet_earned
- pilot_only
- pilot_ready
- ready_to_scale
predicted_decision_state:
type: string
enum:
- permission_not_yet_earned
- pilot_only
- pilot_ready
- ready_to_scale
- abstained
country:
type: string
predicted_at:
type: string
format: date-time
decision_date:
type: string
format: date-time
enrollment_id:
type: string
minLength: 1
consent_to_outcome_processing:
type: boolean
const: true
outcome_class:
type: string
enum:
- favorable
- mixed
- unfavorable
- indeterminate
decision_execution_status:
type: string
enum:
- within_authorized_boundary
- beyond_authorized_boundary
- not_executed
- unknown
verification_status:
type: string
enum:
- self_reported
- document_supported
- independently_verified
- disputed
outcome_date:
type: string
format: date-time
observed_at:
type: string
format: date-time
source_references:
type: array
maxItems: 12
items:
type: object
additionalProperties: false
properties:
reference_id:
type: string
description: Governed reference identifier; persisted only as a server-keyed token.
source_class:
type: string
enum:
- governed_internal_record
- public_record
- regulatory_record
- transactional_record
- independent_attestation
- field_observation
- other_governed_reference
source_hash:
type: string
pattern: ^[A-Fa-f0-9]{64}$
observed_at:
type: string
format: date-time
limit:
type: integer
minimum: 1
maximum: 100
confirm_withdrawal:
type: boolean
const: true
additionalProperties: true
required:
- enrollment_id
description: Delegates to outcome-ledger, default action record_outcome. Requires prospective enrollment; no direct self-asserted outcome enters calibration. See outcome-ledger for action-specific conditional requirements.
tags:
- Outcome Feedback
operationId: postV1OutcomeFeedback
x-operation-id-source: derived
components:
headers:
WorkerElapsed:
description: Aggregate Worker elapsed milliseconds to response construction, excluding delivery and background work. Worker clocks advance after I/O; this is not CPU time and cannot isolate network latency. No infrastructure or tenant identities are exposed.
schema:
type: string
example: mvr;dur=42;desc="Worker elapsed to response"
schemas:
CalibrationDisposition:
type: object
description: A serving hold, not empirical validation. Governed retirement requires a verified retirement record; otherwise the hold is quarantined. Neither permits substitution.
required:
- status
- namespace
- key
- manifest_key
- serving_prohibited
- replacement_available
- source_truth_verified
- attested
- retirement_verified
properties:
status:
type: string
enum:
- calibration_retired
- calibration_quarantined
namespace:
type: string
key:
type: string
manifest_key:
type: string
decision_ref:
type: string
reason_code:
type: string
approved_at:
type: string
format: date-time
serving_prohibited:
type: boolean
enum:
- true
replacement_available:
type: boolean
enum:
- false
source_truth_verified:
type: boolean
enum:
- false
attested:
type: boolean
enum:
- false
retirement_verified:
type: boolean
oneOf:
- properties:
status:
enum:
- calibration_retired
retirement_verified:
enum:
- true
required:
- decision_ref
- reason_code
- approved_at
- properties:
status:
enum:
- calibration_quarantined
retirement_verified:
enum:
- false
additionalProperties: true
ReceiptEvidenceFinding:
type: object
required:
- path
- evidence_id
- marker
- path_truncated
- evidence_id_truncated
properties:
path:
type: string
maxLength: 1024
description: RFC 6901 JSON Pointer into the submitted body. Truncated pointers are not directly resolvable.
evidence_id:
type:
- string
- 'null'
maxLength: 160
marker:
type: string
path_truncated:
type: boolean
evidence_id_truncated:
type: boolean
additionalProperties: false
ArtifactRoleEvidenceFinding:
type: object
required:
- path
- evidence_id
- marker
- path_truncated
- evidence_id_truncated
- artifact_role
properties:
path:
type: string
maxLength: 1024
description: RFC 6901 JSON Pointer into the submitted body. Truncated pointers are not directly resolvable.
evidence_id:
type:
- string
- 'null'
maxLength: 160
marker:
type: string
path_truncated:
type: boolean
evidence_id_truncated:
type: boolean
artifact_role:
type: string
enum:
- derived_summary
- model_inferred
- decision_output
- historical_context
- unknown
additionalProperties: false
description: Explicit prohibited role declaration, not source authentication. unknown means an explicit unknown role, never absent classification.
RequestErrorResponse:
type: object
properties:
error:
type: string
code:
type: string
description: 'Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md. Also DUPLICATE_COMPARISON_OPTION_ID for colliding comparison identifiers. HTTP 409 IDEMPOTENCY_CONTEXT_MISMATCH means the original receipt has an old, unknown or changed deployment/response context; it takes precedence over request hash differences. IDEMPOTENCY_REQUEST_MISMATCH means the same context has different payload or hashed request metadata (including User-Agent). Neither re-executes the operation. Reconcile the original request and retain its Idempotency-Key; never change keys to bypass a conflict.'
message:
type: string
details:
type: array
items: {}
assessment_executed:
type: boolean
description: False on pre-assessment output-mode rejection. Absence is not evidence that no assessment ran.
lineage_status:
type: string
field:
type: string
description: Caller field that mismatched server-persisted decision lineage.
receipt_evidence_findings:
type: array
maxItems: 15
items:
$ref: '#/components/schemas/ReceiptEvidenceFinding'
receipt_validation:
type: object
properties:
performed:
type: boolean
enum:
- false
status:
type: string
enum:
- not_checked
validity:
type: string
enum:
- unknown
expiry:
type: string
enum:
- unknown
revocation:
type: string
enum:
- unknown
total_errors:
type: integer
minimum: 0
validation_errors_truncated:
type: boolean
calibration_disposition:
$ref: '#/components/schemas/CalibrationDisposition'
artifact_role_findings:
type: array
maxItems: 15
items:
$ref: '#/components/schemas/ArtifactRoleEvidenceFinding'
strict_eligible:
type: boolean
enum:
- false
schema_and_reviewer_eligible:
type: boolean
enum:
- false
duplicate_option_ids:
type: array
items:
type: string
uniqueItems: true
description: Resolved comparison IDs that collided after the documented alias precedence and positional fallback. Present with DUPLICATE_COMPARISON_OPTION_ID; HTTP 422.
status:
type: string
response_meta:
type: object
properties:
deployment_revision:
type: string
additionalProperties: true
additionalProperties: true
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.