africanmarketos-com Connectors API

openapi: 3.2.0
info:
  title: MVR Core API - Full Expert Catalogue Connectors 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: Connectors
paths:
  /v1/connectors/catalog:
    get:
      summary: Return supported connector types, accepted metrics, and normalization guidance
      description: Return supported connector types, accepted metrics, and normalization guidance.
      parameters: []
      x-mvr-registry-route: /v1/connectors/catalog
      x-mvr-maturity: release_candidate
      x-mvr-labels:
      - board_safe_supported
      x-mvr-validator-contract:
        name: validateConnectorsCatalog
        status: registry_metadata_enforced_by_shared_gateway
      x-mvr-idempotency-key-required: false
      x-mvr-idempotency-policy:
        mode: not_required
      x-mvr-access:
        plans:
        - STANDARD
        - 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:
      - Connectors
      operationId: getV1ConnectorsCatalog
      x-operation-id-source: derived
  /v1/connectors/normalize:
    post:
      summary: Canonical connector normalizer for CRM, HRIS, ERP/inventory, and compliance…
      description: Canonical connector normalization route for structured enterprise metrics.
      parameters: []
      x-mvr-registry-route: /v1/connectors/normalize
      x-mvr-maturity: release_candidate
      x-mvr-labels:
      - connector_normalization
      - enterprise_integration
      - plan_gated
      - board_safe_supported
      x-mvr-validator-contract:
        name: validateConnectorsNormalize
        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
              properties:
                output_mode:
                  type: string
                  enum:
                  - internal_full
                  - client_safe
                  - board_safe
                response_profile:
                  type: string
                  enum:
                  - full_advisory
                  - strict_calibrated
                source_type:
                  type: string
                connector_type:
                  type: string
                source_name:
                  type: string
                raw_metrics:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                metrics:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                raw_data:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                data:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                evidence_geography:
                  $ref: '#/components/schemas/UtilityMarketScope'
                country:
                  type: string
                metadata_map:
                  type: object
                  properties:
                    freshness_date:
                      type: string
                      description: ISO calendar date or timestamp.
                    collected_at:
                      type: string
                      description: ISO calendar date or timestamp.
                    source_period_end:
                      type: string
                      description: ISO calendar date or timestamp.
                    source_name:
                      type: string
                    collector:
                      type: string
                    source_doc_id:
                      type: string
                    source_locator:
                      type: string
                    source_family:
                      type: string
                    extraction_method:
                      type: string
                    extraction_confidence:
                      type: number
                      minimum: 0
                      maximum: 1
                    compiler_stage:
                      type: string
                    fieldname_map:
                      type: object
                      additionalProperties:
                        type: string
                  additionalProperties:
                    $ref: '#/components/schemas/TelemetrySourceMetadata'
                  description: Flat source metadata or a map from telemetry section/metric to source metadata. Strict telemetry requires dated metadata per used source.
                metadata:
                  $ref: '#/components/schemas/TelemetrySourceMetadata'
                fieldname_map:
                  type: object
                  additionalProperties:
                    type: string
                field_map:
                  type: object
                  additionalProperties:
                    type: string
                freshness_date:
                  type: string
                  description: ISO calendar date or timestamp.
                source_period_end:
                  type: string
                  description: ISO calendar date or timestamp.
                maturity:
                  type: string
                maturity_level:
                  type: string
                subject:
                  $ref: '#/components/schemas/UtilitySubject'
              additionalProperties: true
              allOf:
              - anyOf:
                - required:
                  - source_type
                - required:
                  - connector_type
              - anyOf:
                - required:
                  - evidence_geography
                  properties:
                    evidence_geography:
                      type: object
                      anyOf:
                      - required:
                        - country
                        properties:
                          country:
                            type: string
                            minLength: 1
                - required:
                  - country
                  properties:
                    country:
                      type: string
                      minLength: 1
              description: 'Supported source types: crm, hris, erp_inventory, compliance, pos, program_monitoring, fleet_operations, field_operations. salesforce_crm aliases crm. Supply mapped metrics, a valid source country and dated source metadata. Normalization creates proxy evidence, not observed facts.'
            example:
              source_type: crm
              source_name: HubSpot export
              evidence_geography:
                country: UG
                region: Kampala
              metadata_map:
                freshness_date: '2026-04-20'
                source_doc_id: crm-export-2026-04
                source_locator: s3://bucket/key.csv
                extraction_method: deterministic_parser
                extraction_confidence: 0.94
                compiler_stage: source_normalize
              raw_metrics:
                nps_score: 42
                customer_complaint_rate: 7
      x-mvr-example:
        profiles:
        - full_advisory
        - strict_calibrated
        plans:
        - PRO
        - ENTERPRISE
        required_roles_any: []
        after: []
        copy: []
        headers: []
        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:
      - Connectors
      operationId: postV1ConnectorsNormalize
      x-operation-id-source: derived
  /v1/connectors/validate-export:
    post:
      summary: Validate an exported business data file manifest before source normalization
      description: Validate an exported business data file manifest before source normalization.
      parameters: []
      x-mvr-registry-route: /v1/connectors/validate-export
      x-mvr-maturity: release_candidate
      x-mvr-labels: []
      x-mvr-validator-contract:
        name: validateConnectorExport
        status: registry_metadata_enforced_by_shared_gateway
      x-mvr-idempotency-key-required: false
      x-mvr-idempotency-policy:
        mode: not_required
      x-mvr-access:
        plans:
        - STANDARD
        - PRO
        - ENTERPRISE
        required_roles_any: []
        output_modes:
        - internal_full
        - client_safe
        break_glass_allowed: false
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Successful response
          headers:
            Server-Timing:
              $ref: '#/components/headers/WorkerElapsed'
        '400':
          description: Bad request
          headers:
            Server-Timing:
              $ref: '#/components/headers/WorkerElapsed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '403':
          description: Forbidden
          headers:
            Server-Timing:
              $ref: '#/components/headers/WorkerElapsed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '404':
          description: Not found
          headers:
            Server-Timing:
              $ref: '#/components/headers/WorkerElapsed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '409':
          description: Conflict. For idempotent operations, reconcile IDEMPOTENCY_CONTEXT_MISMATCH or IDEMPOTENCY_REQUEST_MISMATCH without changing the original key to bypass the conflict.
          headers:
            Server-Timing:
              $ref: '#/components/headers/WorkerElapsed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '422':
          description: Validation or calibration failure
          headers:
            Server-Timing:
              $ref: '#/components/headers/WorkerElapsed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '429':
          description: Rate or compute limit exceeded
          headers:
            Server-Timing:
              $ref: '#/components/headers/WorkerElapsed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                output_mode:
                  type: string
                  enum:
                  - internal_full
                  - client_safe
                response_profile:
                  type: string
                  enum:
                  - full_advisory
                  - strict_calibrated
                source_type:
                  type: string
                connector_type:
                  type: string
                source_name:
                  type: string
                raw_metrics:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                metrics:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                raw_data:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                data:
                  type: object
                  additionalProperties:
                    anyOf:
                    - type: number
                    - type: string
                evidence_geography:
                  $ref: '#/components/schemas/UtilityMarketScope'
                country:
                  type: string
                metadata_map:
                  type: object
                  properties:
                    freshness_date:
                      type: string
                      description: ISO calendar date or timestamp.
                    collected_at:
                      type: string
                      description: ISO calendar date or timestamp.
                    source_period_end:
                      type: string
                      description: ISO calendar date or timestamp.
                    source_name:
                      type: string
                    collector:
                      type: string
                    source_doc_id:
                      type: string
                    source_locator:
                      type: string
                    source_family:
                      type: string
                    extraction_method:
                      type: string
                    extraction_confidence:
                      type: number
                      minimum: 0
                      maximum: 1
                    compiler_stage:
                      type: string
                    fieldname_map:
                      type: object
                      additionalProperties:
                        type: string
                  additionalProperties:
                    $ref: '#/components/schemas/TelemetrySourceMetadata'
                  description: Flat source metadata or a map from telemetry section/metric to source metadata. Strict telemetry requires dated metadata per used source.
                metadata:
                  $ref: '#/components/schemas/TelemetrySourceMetadata'
                fieldname_map:
                  type: object
                  additionalProperties:
                    type: string
                field_map:
                  type: object
                  additionalProperties:
                    type: string
                freshness_date:
                  type: string
                  description: ISO calendar date or timestamp.
                source_period_end:
                  type: string
                  description: ISO calendar date or timestamp.
                maturity:
                  type: string
                maturity_level:
                  type: string
                subject:
                  $ref: '#/components/schemas/UtilitySubject'
              additionalProperties: true
              description: Checks source_name, freshness and nonempty supported field map. Missing metadata returns review_required; malformed or future-dated metadata fails validation.
      tags:
      - Connectors
      operationId: postV1ConnectorsValidateExport
      x-operation-id-source: derived
components:
  schemas:
    TelemetrySourceMetadata:
      type: object
      properties:
        freshness_date:
          type: string
          description: ISO calendar date or timestamp.
        collected_at:
          type: string
          description: ISO calendar date or timestamp.
        source_period_end:
          type: string
          description: ISO calendar date or timestamp.
        source_name:
          type: string
        collector:
          type: string
        source_doc_id:
          type: string
        source_locator:
          type: string
        source_family:
          type: string
        extraction_method:
          type: string
        extraction_confidence:
          type: number
          minimum: 0
          maximum: 1
        compiler_stage:
          type: string
        fieldname_map:
          type: object
          additionalProperties:
            type: string
      additionalProperties: true
    UtilityMarketScope:
      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
    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
    UtilitySubject:
      type: object
      properties:
        entity_name:
          type: string
        entity_id:
          type: string
        name:
          type: string
        entity_type:
          type: string
        entity_archetype:
          type: string
        category:
          type: string
        country:
          type: string
        project_id:
          type: string
      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


# --- truncated at 32 KB (37 KB total) ---
# Full source: https://artifacts.apis.io/africanmarketos-com/openapi/africanmarketos-com-connectors-api-openapi.yml