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 Tasks 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: Tasks
paths:
/v1/tasks/create:
post:
summary: Persist evidence collection tasks generated by gap plans or evidence-run…
description: Persist evidence collection tasks generated by gap plans or evidence-run orchestration. 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/tasks/create
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
- board_safe_supported
- requires_kv
x-mvr-validator-contract:
name: validateTaskCreate
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'
'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: true
properties:
project_id:
type: string
run_id:
type: string
priority:
type: string
geo_target: {}
target_market:
type: object
additionalProperties: true
task:
type: object
additionalProperties: true
properties:
task_id:
type: string
project_id:
type: string
run_id:
type: string
status:
type: string
description: 'Case-normalized: open, assigned, in_review, approved, rejected, closed'
priority:
type: string
description: 'Case-normalized: low, medium, high, critical'
stakeholder_class:
type: string
geo_target: {}
required_fields:
type: array
items: {}
min_n:
type: integer
minimum: 0
reason:
type: string
assigned_to_role:
type: string
guardian_tier_required:
type: string
tasks:
type: array
minItems: 1
items:
type: object
additionalProperties: true
properties:
task_id:
type: string
project_id:
type: string
run_id:
type: string
status:
type: string
description: 'Case-normalized: open, assigned, in_review, approved, rejected, closed'
priority:
type: string
description: 'Case-normalized: low, medium, high, critical'
stakeholder_class:
type: string
geo_target: {}
required_fields:
type: array
items: {}
min_n:
type: integer
minimum: 0
reason:
type: string
assigned_to_role:
type: string
guardian_tier_required:
type: string
evidence_tasks:
type: array
minItems: 1
items:
type: object
additionalProperties: true
properties:
task_id:
type: string
project_id:
type: string
run_id:
type: string
status:
type: string
description: 'Case-normalized: open, assigned, in_review, approved, rejected, closed'
priority:
type: string
description: 'Case-normalized: low, medium, high, critical'
stakeholder_class:
type: string
geo_target: {}
required_fields:
type: array
items: {}
min_n:
type: integer
minimum: 0
reason:
type: string
assigned_to_role:
type: string
guardian_tier_required:
type: string
anyOf:
- required:
- task
- required:
- tasks
- required:
- evidence_tasks
description: 'Requires Idempotency-Key and at least one task. Every task requires project_id or run_id, locally or at top level. Task fields: task_id, project_id, run_id, status (open, assigned, in_review, approved, rejected, closed), priority (low, medium, high, critical), stakeholder_class, geo_target, required_fields, min_n (integer >=0), reason, assigned_to_role and guardian_tier_required. Status and priority are case-normalized. A task is a request for evidence, not accepted evidence.'
examples:
- project_id: fictional-project
tasks:
- task_id: fictional-task
reason: Record dated dealer observations
min_n: 3
example:
project_id: project-001
run_id: run-001
tasks:
- priority: high
stakeholder_class: guardian
geo_target: KE
required_fields:
- guardian_strength
- stance
min_n: 2
reason: Guardian signal missing.
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:
- Tasks
operationId: postV1TasksCreate
x-operation-id-source: derived
/v1/tasks/list:
post:
summary: List persisted evidence tasks by tenant, workspace, project, run, or status
description: List persisted evidence tasks by tenant, workspace, project, run, or status.
parameters: []
x-mvr-registry-route: /v1/tasks/list
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
- board_safe_supported
- requires_kv
x-mvr-validator-contract:
name: validateTaskList
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'
'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: true
properties:
project_id:
type: string
run_id:
type: string
status:
type: string
limit:
anyOf:
- type: integer
- type: string
cursor:
type: string
next_page_token:
type: string
description: Tenant/workspace task listing; empty input is allowed. Follow the returned opaque cursor. status or run_id filters are restricted to one bounded page and cannot be combined with cursor/next_page_token. The canonical store caps a storage page at 200 records. No notification or review is scheduled.
examples:
- project_id: fictional-project
limit: 20
tags:
- Tasks
operationId: postV1TasksList
x-operation-id-source: derived
get:
summary: List persisted evidence tasks by tenant, workspace, project, run, or status
description: List persisted evidence tasks by tenant, workspace, project, run, or status.
parameters: []
x-mvr-registry-route: /v1/tasks/list
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
- board_safe_supported
- requires_kv
x-mvr-validator-contract:
name: validateTaskList
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'
'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:
- Tasks
operationId: getV1TasksList
x-operation-id-source: derived
/v1/tasks/update:
post:
summary: Update evidence task status, assignment, priority, or review metadata
description: Update evidence task status, assignment, priority, or review metadata.
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/tasks/update
x-mvr-maturity: release_candidate
x-mvr-labels:
- plan_gated
- board_safe_supported
- requires_kv
x-mvr-validator-contract:
name: validateTaskUpdate
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'
'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: true
required:
- project_id
- task_id
properties:
project_id:
type: string
minLength: 1
task_id:
type: string
minLength: 1
status:
type: string
priority:
type: string
assigned_to_role:
type: string
required_fields:
type: array
items: {}
review_notes:
type: string
anyOf:
- required:
- status
- required:
- priority
- required:
- assigned_to_role
- required:
- required_fields
- required:
- review_notes
description: 'Requires Idempotency-Key and an existing task in the named project and authenticated scope. status values: open, assigned, in_review, approved, rejected, closed; priority: low, medium, high, critical. Both are case-normalized. At least one supported update field is required. Closing a task does not certify the collected evidence.'
examples:
- project_id: fictional-project
task_id: fictional-task
status: closed
review_notes: Synthetic contract example only
tags:
- Tasks
operationId: postV1TasksUpdate
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
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://artifacts.apis.io/africanmarketos-com/openapi/africanmarketos-com-tasks-api-openapi.yml