{
  "openapi": "3.1.0",
  "info": {
    "title": "Primer International Market Systems Development (MSD) API",
    "version": "1.0.0",
    "description": "Public edge API and MCP server providing unified access to global Market Systems Development (MSD / M4P) evidence, DCED results measurement standards, BEAM Exchange tool libraries, and quantitative commercial deal calculators.",
    "contact": {
      "name": "Primer International Practice Lead",
      "email": "primer@linn.services",
      "url": "https://primer.linn.services/market-systems/"
    },
    "license": {
      "name": "Open Data Access (Fair Use / Creative Commons Attribution)",
      "url": "https://beamexchange.org"
    }
  },
  "servers": [
    {
      "url": "https://msd.linn.services",
      "description": "Cloudflare Edge Global Network (APAC / Americas / EMEA)"
    }
  ],
  "paths": {
    "/v1/stats": {
      "get": {
        "summary": "Retrieve MSD Evidence Inventory Statistics",
        "description": "Returns catalog counts for DCED standards, BEAM tools, evaluated programmes, resource library documents, and last sync timestamp.",
        "responses": {
          "200": {
            "description": "Successful response with inventory metrics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Search MSD Knowledge Base with Reciprocal Rank Fusion",
        "description": "Full-text search across DCED guidance, BEAM tools, programmes, and resource documents.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search keywords (e.g., cost-share, attribution, results chain)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by document type (all, dced, tool, programme, resource)",
            "schema": {
              "type": "string",
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return (1-50)",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results ordered by Reciprocal Rank Fusion relevance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "total_matches": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tools": {
      "get": {
        "summary": "Browse BEAM MSD Tools Library",
        "description": "Returns practical implementation tools, diagnostic guides, and operational templates.",
        "parameters": [
          {
            "name": "stage",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of tools"
          }
        }
      }
    },
    "/v1/tools/{id}": {
      "get": {
        "summary": "Get Tool by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool details"
          },
          "404": {
            "description": "Tool not found"
          }
        }
      }
    },
    "/v1/programmes": {
      "get": {
        "summary": "Browse Evaluated MSD Programmes",
        "description": "Returns cataloged donor-funded market systems programmes.",
        "parameters": [
          {
            "name": "donor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of programmes"
          }
        }
      }
    },
    "/v1/programmes/{id}": {
      "get": {
        "summary": "Get Programme by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Programme details"
          },
          "404": {
            "description": "Programme not found"
          }
        }
      }
    },
    "/v1/resources": {
      "get": {
        "summary": "Browse BEAM Resource Library",
        "description": "Returns evaluated case studies, research papers, and policy briefs.",
        "parameters": [
          {
            "name": "sector",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of resources"
          }
        }
      }
    },
    "/v1/resources/{id}": {
      "get": {
        "summary": "Get Resource by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resource details"
          },
          "404": {
            "description": "Resource not found"
          }
        }
      }
    },
    "/v1/dced": {
      "get": {
        "summary": "Browse DCED Standard Guidance Pages",
        "description": "Returns official Donor Committee for Enterprise Development guidance documents.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of DCED guidance pages"
          }
        }
      }
    },
    "/v1/dced/{id}": {
      "get": {
        "summary": "Get DCED Page by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DCED page details"
          },
          "404": {
            "description": "DCED page not found"
          }
        }
      }
    },
    "/v1/calculate/deal": {
      "post": {
        "summary": "Calculate Rural Dealer Economics and Inflation Decay",
        "description": "Evaluates dealer profit margins, working capital requirements, monthly inflation capital decay, and smallholder payback periods.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "retail_price",
                  "wholesale_price",
                  "monthly_volume_units",
                  "dealer_fixed_cost_monthly",
                  "cash_cycle_days",
                  "monthly_inflation_rate_pct",
                  "farmer_equipment_cost",
                  "farmer_seasonal_revenue_gain",
                  "donor_subsidy_grant",
                  "partner_equity_match"
                ],
                "properties": {
                  "retail_price": {
                    "type": "number",
                    "example": 120
                  },
                  "wholesale_price": {
                    "type": "number",
                    "example": 95
                  },
                  "monthly_volume_units": {
                    "type": "integer",
                    "example": 30
                  },
                  "dealer_fixed_cost_monthly": {
                    "type": "number",
                    "example": 250
                  },
                  "cash_cycle_days": {
                    "type": "integer",
                    "example": 10
                  },
                  "monthly_inflation_rate_pct": {
                    "type": "number",
                    "example": 3.5
                  },
                  "farmer_equipment_cost": {
                    "type": "number",
                    "example": 120
                  },
                  "farmer_seasonal_revenue_gain": {
                    "type": "number",
                    "example": 160
                  },
                  "donor_subsidy_grant": {
                    "type": "number",
                    "example": 35000
                  },
                  "partner_equity_match": {
                    "type": "number",
                    "example": 45000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deal assessment results with PASS / FAIL status and markdown summary"
          }
        }
      }
    },
    "/v1/calculate/dced": {
      "post": {
        "summary": "Compute DCED Attributable Net Additional Income (NAI)",
        "description": "Calculates defensible attributable net additional income and full-time equivalent employment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "beneficiaries_reached",
                  "gross_additional_income_per_beneficiary",
                  "deadweight_pct",
                  "displacement_pct",
                  "substitution_pct",
                  "crowding_in_multiplier",
                  "direct_partner_jobs_created",
                  "additional_labor_days_per_beneficiary",
                  "program_intervention_cost"
                ],
                "properties": {
                  "beneficiaries_reached": {
                    "type": "integer",
                    "example": 2500
                  },
                  "gross_additional_income_per_beneficiary": {
                    "type": "number",
                    "example": 180
                  },
                  "deadweight_pct": {
                    "type": "number",
                    "example": 15
                  },
                  "displacement_pct": {
                    "type": "number",
                    "example": 10
                  },
                  "substitution_pct": {
                    "type": "number",
                    "example": 5
                  },
                  "crowding_in_multiplier": {
                    "type": "number",
                    "example": 1.25
                  },
                  "direct_partner_jobs_created": {
                    "type": "integer",
                    "example": 8
                  },
                  "additional_labor_days_per_beneficiary": {
                    "type": "number",
                    "example": 12
                  },
                  "program_intervention_cost": {
                    "type": "number",
                    "example": 65000
                  },
                  "working_days_per_fte": {
                    "type": "integer",
                    "default": 240
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DCED attribution audit results and markdown report"
          }
        }
      }
    },
    "/v1/lint": {
      "post": {
        "summary": "Audit Proposal Text for MSD Anti-Patterns",
        "description": "Inspects proposal narratives for direct equipment handouts, pure grants, missing attribution deductions, and currency peg risks.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "Proposal draft text to audit"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Linter findings, severity breakdown, and remediation advice"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "Model Context Protocol (MCP) Streamable HTTP Endpoint",
        "description": "Zero-auth JSON-RPC 2.0 endpoint for AI assistants (Claude Desktop, Cursor, Gemini, Antigravity) providing tools and resources.",
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      }
    }
  }
}