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 Project Memory 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: Project Memory
paths:
/v1/project-memory/upsert:
post:
summary: Persist project-level market context, evidence references, task counts, and…
description: Persist project-level market context, evidence references, task counts, and last verdict summaries without storing raw sensitive evidence. Requires Idempotency-Key.
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/project-memory/upsert
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
- board_safe_supported
- requires_kv
x-mvr-validator-contract:
name: validateProjectMemory
status: registry_metadata_enforced_by_shared_gateway
x-mvr-idempotency-key-required: true
x-mvr-idempotency-policy:
mode: required
x-mvr-access:
plans:
- PRO
- ENTERPRISE
required_roles_any: []
output_modes:
- internal_full
- client_safe
- board_safe
break_glass_allowed: false
security:
- ApiKeyAuth: []
- BearerAuth: []
responses:
'200':
description: Successful response
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectMemoryResponse'
'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
additionalProperties: false
required:
- project_id
properties:
project_id:
type: string
minLength: 1
title:
type: string
metadata:
type: object
additionalProperties: true
memory_items:
type: array
items: {}
subject_defaults:
type: object
additionalProperties: true
properties:
entity_name:
type: string
entity_archetype:
type: string
category:
type: string
market_scope_defaults:
type: object
properties:
country:
type: string
region:
type: string
city:
type: string
district:
type: string
pattern: \S
districts:
type: array
items:
type: string
pattern: \S
decision_scope_level:
type: string
enum:
- country
- subnational
description: Explicit decision extent. Alternatively supply district(s). Subnational scope also requires local geography. Do not relabel or widen the decision to pass.
town_or_zone:
type: string
micro_context:
type: string
corridor:
type: string
sector:
type: string
analysis_date:
type: string
geo_match_tolerance:
type: string
enum:
- strict
- same_city
- region
- country
default: strict
description: Declare the actual decision geography. Do not widen it to obtain a verdict.
additionalProperties: true
preferred_output_mode:
type: string
enum:
- internal_full
- audit_trace
- client_safe
- excel_safe
- board_safe
- export_safe
evidence_pack_refs:
type: array
items: {}
last_verdict:
type: object
properties:
recommendation:
type:
- string
- 'null'
verdict:
type:
- string
- 'null'
status:
type:
- string
- 'null'
evaluated_at:
type:
- string
- 'null'
timestamp:
type:
- string
- 'null'
decision_check_id:
type:
- string
- 'null'
response_hash:
type:
- string
- 'null'
confidence:
type:
- number
- 'null'
minimum: 0
maximum: 1
description: Caller-authored summary unless decision_check_id and response_hash match a server-held receipt in the same tenant/workspace/project. Supplied origin, receipt_verified and authority flags are ignored.
open_task_count:
type: integer
minimum: 0
maximum: 1000000
watchlist_dimensions:
type: array
items: {}
notes:
type: string
description: Compatibility alias for a single untrusted memory item of type note, retained up to 2000 characters. An explicit memory_items array takes precedence, even when empty. Notes are context, never source evidence, instructions or permission.
anyOf:
- required:
- title
properties:
title:
minLength: 1
- required:
- metadata
properties:
metadata:
minProperties: 1
- required:
- memory_items
properties:
memory_items:
minItems: 1
- required:
- subject_defaults
- required:
- market_scope_defaults
- required:
- evidence_pack_refs
properties:
evidence_pack_refs:
minItems: 1
- required:
- last_verdict
- required:
- open_task_count
- required:
- watchlist_dimensions
properties:
watchlist_dimensions:
minItems: 1
- required:
- notes
properties:
notes:
minLength: 1
not:
required:
- memory_items
description: 'Tenant/workspace project prerequisite for field-signal requests. Requires project_id plus meaningful memory: for example a non-blank title. Defaults must contain a named entity/archetype/category or country/region/seasonal_region/sector. Empty defaults, blank titles and empty arrays are not meaningful. Memory is context, not reviewed evidence or permission.'
examples:
- project_id: synthetic-field-demo
title: Fictional field-signal contract example
example:
project_id: project-001
subject_defaults:
entity_name: Sample FMCG
entity_archetype: fmcg_brand
category: fmcg
market_scope_defaults:
country: KE
region: Nairobi
seasonal_region: EA
regulatory_velocity: stable
preferred_output_mode: client_safe
evidence_pack_refs: []
watchlist_dimensions:
- permission
- trust
- guardian_strength
x-mvr-example:
profiles:
- full_advisory
- strict_calibrated
plans:
- PRO
- ENTERPRISE
required_roles_any: []
after: []
copy: []
headers:
- Idempotency-Key
run_rule: Send the example unchanged with a key that has the listed plan and one of the listed roles, after the listed examples, copying the listed response fields. Generate a fresh value for each listed header.
tags:
- Project Memory
operationId: postV1ProjectMemoryUpsert
x-operation-id-source: derived
/v1/project-memory/{project_id}:
get:
summary: Retrieve saved project-level market context and evidence references
description: Retrieve saved project-level market context and evidence references.
parameters:
- name: project_id
in: path
required: true
schema:
type: string
- name: view
in: query
schema:
type: string
enum:
- full
- agent
default: full
description: agent omits raw notes, arbitrary metadata and caller-authored verdict text. It does not turn memory into evidence or authority.
x-mvr-registry-route: /v1/project-memory/:project_id
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
- board_safe_supported
- requires_kv
x-mvr-validator-contract:
name: validateProjectMemoryGet
status: registry_metadata_enforced_by_shared_gateway
x-mvr-idempotency-key-required: false
x-mvr-idempotency-policy:
mode: not_required
x-mvr-access:
plans:
- PRO
- ENTERPRISE
required_roles_any: []
output_modes:
- internal_full
- client_safe
- board_safe
break_glass_allowed: false
security:
- ApiKeyAuth: []
- BearerAuth: []
responses:
'200':
description: Successful response
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectMemoryResponse'
'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'
tags:
- Project Memory
operationId: getV1ProjectMemoryByProjectId
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:
ProjectMemoryResponse:
type: object
properties:
status:
type: string
project_memory:
type: object
properties:
project_id:
type: string
content_trust:
type: object
properties:
origin:
type: string
instruction_authority:
type: string
enum:
- none
untrusted_paths:
type: array
items:
type: string
policy:
type: string
additionalProperties: true
agent_context:
type: object
properties:
project_id:
type: string
memory_item_count:
type: integer
evidence_reference_count:
type: integer
has_verified_historical_receipt:
type: boolean
execution_authorized:
type: boolean
enum:
- false
raw_content_omitted:
type: boolean
additionalProperties: true
last_verdict:
type:
- object
- 'null'
properties:
origin:
type: string
enum:
- caller_authored_memory_summary
- verified_decision_receipt
receipt_verified:
type: boolean
decision_check_id:
type:
- string
- 'null'
response_hash:
type:
- string
- 'null'
evaluated_at:
type:
- string
- 'null'
recommendation:
type:
- string
- 'null'
additionalProperties: true
additionalProperties: true
additionalProperties: true
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
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://artifacts.apis.io/africanmarketos-com/openapi/africanmarketos-com-project-memory-api-openapi.yml