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 Key Ceremony 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: Key Ceremony
paths:
/v1/key-ceremony:
post:
summary: 'Made-in-Cloudflare receipt key ceremony: precheck, run once, confirm token…'
description: 'Made-in-Cloudflare receipt key ceremony: precheck, run once, confirm token deletion, or recover an interrupted run. The Cloudflare API token in the body is the authority; it is never stored. Grants no permission.'
parameters: []
x-mvr-registry-route: /v1/key-ceremony
x-mvr-maturity: release_candidate
x-mvr-labels: []
x-mvr-validator-contract:
name: none
status: none
x-mvr-idempotency-key-required: false
x-mvr-idempotency-policy:
mode: not_required
x-mvr-access:
plans:
- PUBLIC
- STANDARD
- PRO
- ENTERPRISE
required_roles_any: []
output_modes:
- client_safe
break_glass_allowed: false
security: []
responses:
'200':
description: Successful response
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/KeyCeremonyResponse'
'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:
- action
properties:
action:
enum:
- precheck
- run
- check_token
- recover_interrupted
ceremony_id:
type: string
pattern: ^KC-AMOS-RECEIPT-20[0-9]{2}-[0-9]{2}$
key_id:
type: string
pattern: ^amos-receipt-ed25519-20[0-9]{2}-[0-9]{2}$
participants_sha256:
type: string
pattern: ^[a-f0-9]{64}$
cloudflare_api_token:
type: string
minLength: 30
maxLength: 200
writeOnly: true
confirm_witnesses_present:
type: boolean
tags:
- Key Ceremony
operationId: postV1KeyCeremony
x-operation-id-source: derived
/v1/key-ceremony/status:
get:
summary: Public state of the receipt key ceremony, the signed birth record and its…
description: Public state of the receipt key ceremony, the signed birth record and its verification, and the private key binding metadata (never the key).
parameters: []
x-mvr-registry-route: /v1/key-ceremony/status
x-mvr-maturity: release_candidate
x-mvr-labels: []
x-mvr-validator-contract:
name: none
status: none
x-mvr-idempotency-key-required: false
x-mvr-idempotency-policy:
mode: not_required
x-mvr-access:
plans:
- PUBLIC
- STANDARD
- PRO
- ENTERPRISE
required_roles_any: []
output_modes:
- client_safe
break_glass_allowed: false
security: []
responses:
'200':
description: Successful response
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/KeyCeremonyStatus'
'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:
- Key Ceremony
operationId: getV1KeyCeremonyStatus
x-operation-id-source: derived
/v1/key-ceremony/contract:
get:
summary: How the made-in-Cloudflare receipt key ceremony works, its refusals and custody
description: How the made-in-Cloudflare receipt key ceremony works, its refusals and custody.
parameters: []
x-mvr-registry-route: /v1/key-ceremony/contract
x-mvr-maturity: release_candidate
x-mvr-labels: []
x-mvr-validator-contract:
name: none
status: none
x-mvr-idempotency-key-required: false
x-mvr-idempotency-policy:
mode: not_required
x-mvr-access:
plans:
- PUBLIC
- STANDARD
- PRO
- ENTERPRISE
required_roles_any: []
output_modes:
- client_safe
break_glass_allowed: false
security: []
responses:
'200':
description: Successful response
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
content:
application/json:
schema:
$ref: '#/components/schemas/KeyCeremonyContract'
'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:
- Key Ceremony
operationId: getV1KeyCeremonyContract
x-operation-id-source: derived
components:
schemas:
KeyCeremonyContract:
type: object
properties:
contract_version:
type: string
route:
type: string
actions:
type: object
properties: {}
additionalProperties: true
request:
type: object
properties: {}
additionalProperties: true
custody:
type: object
properties: {}
additionalProperties: true
order:
type: array
items:
type: string
refusals:
type: array
items:
type: string
rate_limits:
type: object
properties:
per_client_ip_per_hour:
type: integer
global_per_hour:
type: integer
additionalProperties: true
key_status:
type: object
properties: {}
additionalProperties: true
boundary:
type: string
additionalProperties: true
required:
- contract_version
- route
- refusals
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
KeyCeremonyResponse:
type: object
properties:
status:
type: string
enum:
- ready
- completed
- refused
- token_active
- recovered
code:
type: string
http_status:
type: integer
contract_version:
type: string
ceremony_id:
type: string
key_id:
type: string
participants_sha256:
type: string
worker_script:
type: string
deployment_revision:
type: string
token:
type: object
properties:
kind:
type: string
enum:
- user
- account
id_sha256:
type: string
expires_on:
type: string
additionalProperties: true
deployed_version_before:
type: string
deployed_version_after:
type: string
will_create:
type: array
items:
type: string
public_key_fingerprint_sha256:
type: string
birth_record:
type: object
properties:
type:
type: string
enum:
- mvr.receipt-key-birth/1
ceremony_id:
type: string
key_id:
type: string
algorithm:
type: string
enum:
- Ed25519
public_key_spki_b64:
type: string
public_key_fingerprint_sha256:
type: string
participants_sha256:
type: string
generated_at:
type: string
not_before:
type: string
rotation_due_at:
type: string
generated_in:
type: string
enum:
- cloudflare_worker
worker_script:
type: string
deployment_revision:
type: string
deployed_version_before:
type: string
private_key_destination:
type: string
private_key_returned_to_caller:
type: boolean
enum:
- false
cloudflare_token_id_sha256:
type: string
statement:
type: string
additionalProperties: true
birth_signature_b64:
type: string
failed_step:
type: string
cause:
type: string
secrets_written:
type: array
items:
type: string
recovery:
type: string
next:
oneOf:
- type: string
- type: array
items:
type: string
note:
type: string
ceremony:
type: object
properties: {}
additionalProperties: true
execution_authorized:
type: boolean
enum:
- false
issued_by_amos_as_authority:
type: boolean
enum:
- false
grants_permission:
type: boolean
enum:
- false
additionalProperties: true
required:
- status
- execution_authorized
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
KeyCeremonyStatus:
type: object
properties:
contract_version:
type: string
ceremony:
type: object
properties:
state:
type: string
enum:
- not_started
- started
- completed
- failed
- unavailable
- reset_for_rehearsal
ceremony_id:
type: string
key_id:
type: string
started_at:
type: string
completed_at:
type:
- string
- 'null'
failed_step:
type:
- string
- 'null'
failure_code:
type:
- string
- 'null'
public_key_fingerprint_sha256:
type:
- string
- 'null'
birth_record:
type:
- object
- 'null'
properties:
type:
type: string
enum:
- mvr.receipt-key-birth/1
ceremony_id:
type: string
key_id:
type: string
algorithm:
type: string
enum:
- Ed25519
public_key_spki_b64:
type: string
public_key_fingerprint_sha256:
type: string
participants_sha256:
type: string
generated_at:
type: string
not_before:
type: string
rotation_due_at:
type: string
generated_in:
type: string
enum:
- cloudflare_worker
worker_script:
type: string
deployment_revision:
type: string
deployed_version_before:
type: string
private_key_destination:
type: string
private_key_returned_to_caller:
type: boolean
enum:
- false
cloudflare_token_id_sha256:
type: string
statement:
type: string
additionalProperties: true
birth_signature_b64:
type:
- string
- 'null'
additionalProperties: true
required:
- state
registry_activation:
type: string
private_key_binding:
type: object
properties:
present:
type: boolean
type:
type:
- string
- 'null'
algorithm:
type:
- string
- 'null'
extractable:
type:
- boolean
- 'null'
usages:
type:
- array
- 'null'
items:
type: string
additionalProperties: true
ceremony_record_present:
type: boolean
birth_record_verification:
type:
- object
- 'null'
properties:
valid:
type: boolean
checks:
type: object
properties:
format:
type: boolean
fingerprint:
type: boolean
signature:
type: boolean
additionalProperties: true
additionalProperties: true
execution_authorized:
type: boolean
enum:
- false
additionalProperties: true
required:
- ceremony
- registry_activation
- private_key_binding
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"
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
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://artifacts.apis.io/africanmarketos-com/openapi/africanmarketos-com-key-ceremony-api-openapi.yml