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 Export Jobs 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: Export Jobs
paths:
/v1/export-jobs:
post:
summary: Create governed asynchronous export jobs for report, evidence, and decision…
description: Create governed asynchronous export jobs for report, evidence, and decision payloads.
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/export-jobs
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
x-mvr-validator-contract:
name: validateExportJobs
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
- export_safe
break_glass_allowed: false
security:
- ApiKeyAuth: []
- BearerAuth: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ExportJobResponse'
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
'201':
description: Governed historical artifact created; no execution capability.
content:
application/json:
schema:
$ref: '#/components/schemas/ExportJobResponse'
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
- export_safe
response_profile:
type: string
enum:
- full_advisory
- strict_calibrated
action:
type: string
enum:
- create
- delete
job_id:
type: string
pattern: ^EXP-[a-f0-9-]{36}$
format:
type: string
enum:
- pdf
- pdf-ready
- markdown
- csv
title:
type: string
deprecated: true
description: Ignored. The server sets the historical-record title; caller titles cannot imply approval.
project_id:
type: string
decision_check_id:
type: string
pattern: ^DCHK-[A-Za-z0-9-]{1,100}$
response_hash:
type: string
pattern: ^[a-f0-9]{64}$
semantic_decision_hash:
type: string
pattern: ^[a-f0-9]{64}$
snapshot_id:
type: string
minLength: 1
decision_snapshot_id:
type: string
minLength: 1
payload_ref:
type: object
properties:
decision_snapshot_id:
type: string
minLength: 1
additionalProperties: false
required:
- decision_snapshot_id
response_detail:
type: string
enum:
- full
- compact
description: Shared response-envelope detail control. Must agree with X-Response-Detail and any response_detail query parameter; never a source reference or execution permission.
additionalProperties: false
description: Delete requires job_id. Create requires a tenant/workspace-owned persisted decision_check_id plus matching response_hash, or a governed snapshot_id/decision_snapshot_id (also under payload_ref). Inline caller content, verdicts and permissions are rejected in every profile. This is historical decision support, never current clearance or source/institution verification. The artifact carries a dominant BLOCKED execution boundary in every format. Retrieval rechecks lineage and expiry; pre-boundary exports require regeneration. Projected render request is capped at 240000 bytes; output expires after 24 hours.
anyOf:
- required:
- action
- job_id
properties:
action:
enum:
- delete
- properties:
action:
enum:
- create
anyOf:
- required:
- decision_check_id
- response_hash
- required:
- snapshot_id
- required:
- decision_snapshot_id
- required:
- payload_ref
tags:
- Export Jobs
operationId: postV1ExportJobs
x-operation-id-source: derived
/v1/export-jobs/{job_id}:
get:
summary: Retrieve governed export job status
description: Retrieve governed export job status.
parameters:
- name: job_id
in: path
required: true
schema:
type: string
x-mvr-registry-route: /v1/export-jobs/:job_id
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
x-mvr-validator-contract:
name: validateExportJobs
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
- export_safe
break_glass_allowed: false
security:
- ApiKeyAuth: []
- BearerAuth: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ExportJobResponse'
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'
tags:
- Export Jobs
operationId: getV1ExportJobsByJobId
x-operation-id-source: derived
/v1/export-jobs/{job_id}/artifact:
get:
summary: Download a source-bound artifact within its owning workspace
description: Download a source-bound artifact within its owning workspace.
parameters:
- name: job_id
in: path
required: true
schema:
type: string
x-mvr-registry-route: /v1/export-jobs/:job_id/artifact
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
x-mvr-validator-contract:
name: validateExportJobs
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
- export_safe
break_glass_allowed: false
security:
- ApiKeyAuth: []
- BearerAuth: []
responses:
'200':
description: Successful response
content:
application/pdf:
schema:
type: string
format: binary
text/html:
schema:
type: string
format: binary
text/markdown:
schema:
type: string
format: binary
text/csv:
schema:
type: string
format: binary
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'
'410':
description: Legacy or expired export requires regeneration; bytes are not returned.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestErrorResponse'
headers:
Server-Timing:
$ref: '#/components/headers/WorkerElapsed'
'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:
- Export Jobs
operationId: getV1ExportJobsByJobIdArtifact
x-operation-id-source: derived
components:
schemas:
ArtifactBoundary:
type: object
additionalProperties: false
required:
- contract
- headline
- notice
- source_kind
- decision_check_id
- response_hash
- execution_authorized
- capability_issued
- current_reliance_authorized
- source_authenticity_verified
- signer_standing_verified
- revocation_checked
properties:
contract:
type: string
enum:
- mvr-artifact-boundary@2
headline:
type: string
enum:
- 'BLOCKED: NO EXECUTION PERMISSION'
notice:
type: string
enum:
- Historical decision support only. Source claims and institutional authority are not verified by this export. Current reliance requires fresh evaluation and independent authority.
source_kind:
type: string
enum:
- persisted_decision_check
decision_check_id:
type: string
pattern: ^DCHK-[A-Za-z0-9-]{1,100}$
response_hash:
type: string
pattern: ^[a-f0-9]{64}$
execution_authorized:
type: boolean
enum:
- false
capability_issued:
type: boolean
enum:
- false
current_reliance_authorized:
type: boolean
enum:
- false
source_authenticity_verified:
type: boolean
enum:
- false
signer_standing_verified:
type: boolean
enum:
- false
revocation_checked:
type: boolean
enum:
- false
description: Non-authorizing historical artifact boundary. Not a signed permission receipt or proof of source truth, issuer standing, current reliance or revocation checking.
ActionAuthorizationBoundary:
type: object
required:
- contract
- decision
- capability_issued
- execution_authorized
- source_authenticity_verified
- signer_standing_verified
- revocation_checked
- signature
properties:
contract:
type: string
enum:
- mvr-action-boundary@1
decision:
type: string
enum:
- BLOCKED
capability_issued:
type: boolean
enum:
- false
execution_authorized:
type: boolean
enum:
- false
reason:
type: string
source_authenticity_verified:
type: boolean
enum:
- false
signer_standing_verified:
type: boolean
enum:
- false
revocation_checked:
type: boolean
enum:
- false
signature:
enum:
- null
additionalProperties: false
description: Required fail-closed action boundary, not a signed permission capability. Missing, malformed or unknown boundaries must be treated as BLOCKED by the host. This release cannot emit ALLOWED. Independent authority is required outside AMOS. Legacy authorized output-use labels never lift this boundary.
ExportJobResponse:
type: object
properties:
status:
type: string
code:
type: string
job_id:
type: string
job_status:
type: string
job:
type: object
properties:
job_id:
type: string
status:
type: string
schema:
type: string
source_kind:
type: string
source_ref:
type: string
artifact_boundary:
$ref: '#/components/schemas/ArtifactBoundary'
download_url:
type:
- string
- 'null'
file_generation:
type: boolean
expires_at:
type: string
source_sha256:
type: string
artifact_sha256:
type: string
render_spec_sha256:
type: string
mime_type:
type: string
byte_length:
type: integer
minimum: 0
additionalProperties: true
artifact_boundary:
$ref: '#/components/schemas/ArtifactBoundary'
source_kind:
type: string
enum:
- persisted_decision_check
source_ref:
type: string
download_url:
type:
- string
- 'null'
file_generation:
type: boolean
expires_at:
type: string
source_sha256:
type: string
artifact_sha256:
type: string
render_spec_sha256:
type: string
mime_type:
type: string
byte_length:
type: integer
minimum: 0
get_is_read_only:
type: boolean
artifact_access_revoked:
type: boolean
source_deleted:
type: boolean
provenance_note:
type: string
action_authorization:
$ref: '#/components/schemas/ActionAuthorizationBoundary'
additionalProperties: true
description: Governed historical export only. Creation returns 201; deletion 200 preserves the source. Status retrieval is read-only. Legacy/expired jobs return requires_regeneration with no download URL; their artifact URL returns 410. Unknown or inaccessible jobs return 404; changed/missing source lineage rejects retrieval. No export authorizes an action.
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
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 (36 KB total) ---
# Full source: https://artifacts.apis.io/africanmarketos-com/openapi/africanmarketos-com-export-jobs-api-openapi.yml