{
"openapi": "3.1.0",
"info": {
"title": "Middleman Public API",
"version": "1.1.0",
"description": "Anonymous, read-only access to Middleman's public product overview, published Insights, and supplier-independent product identity. Responses do not grant authority to contact, reserve, order, pay, or publish.",
"contact": {
"name": "Middleman",
"url": "https://middlemantechnologies.com"
}
},
"externalDocs": {
"description": "Public API guide",
"url": "https://middleman.mintlify.app/developers/overview"
},
"servers": [
{
"url": "https://middlemantechnologies.com",
"description": "Public production API"
}
],
"security": [],
"tags": [
{
"name": "Overview",
"description": "Middleman's public product description and capability boundary."
},
{
"name": "Insights",
"description": "Published articles with their evidence context."
},
{
"name": "Products",
"description": "Supplier-independent industrial product identity."
}
],
"paths": {
"/api/v1/site": {
"get": {
"operationId": "getMiddlemanSiteOverview",
"summary": "Get the product overview",
"description": "Returns Middleman's public focus, capabilities, release state, and authority boundary.",
"tags": ["Overview"],
"x-mint": {
"metadata": {
"title": "Get the product overview",
"sidebarTitle": "Product overview",
"description": "Read Middleman's public focus, capabilities, release state, and authority boundary.",
"keywords": ["Middleman API", "product overview", "industrial sourcing API"]
},
"content": "This endpoint is anonymous and read-only."
},
"responses": {
"200": {
"description": "Public product overview",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SiteOverviewResponse"
}
}
}
}
}
}
},
"/api/v1/insights": {
"get": {
"operationId": "listMiddlemanInsights",
"summary": "List published Insights",
"description": "Returns summaries of every published Middleman Insight, newest first.",
"tags": ["Insights"],
"x-mint": {
"metadata": {
"title": "List published Insights",
"sidebarTitle": "List Insights",
"description": "List Middleman's published, source-backed industrial sourcing articles.",
"keywords": ["Middleman Insights API", "industrial sourcing articles", "evidence-backed research"]
},
"content": "This endpoint returns published content only. An empty array means no articles are currently published."
},
"responses": {
"200": {
"description": "Published Insight summaries",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InsightListResponse"
}
}
}
}
}
}
},
"/api/v1/insights/{slug}": {
"get": {
"operationId": "getMiddlemanInsight",
"summary": "Get one published Insight",
"description": "Returns one published Insight with its content blocks and evidence register.",
"tags": ["Insights"],
"x-mint": {
"metadata": {
"title": "Get one published Insight",
"sidebarTitle": "Get an Insight",
"description": "Retrieve one published Middleman Insight and its evidence register by slug.",
"keywords": ["Middleman Insight", "evidence register", "published sourcing research"]
},
"content": "Call the list endpoint first when you do not already have an exact slug."
},
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Exact lowercase, hyphenated slug returned by the list endpoint.",
"schema": {
"type": "string",
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
},
"example": "resolve-the-object-before-you-search"
}
],
"responses": {
"200": {
"description": "Published Insight",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InsightResponse"
}
}
}
},
"404": {
"description": "No published Insight has that slug",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}
},
"/api/v1/products/{manufacturer}/{mpn}": {
"get": {
"operationId": "getCanonicalProduct",
"summary": "Resolve a canonical product",
"description": "Returns supplier-independent product identity for an exact manufacturer and manufacturer part number. A match does not confirm current stock, price, condition, or authority to sell.",
"tags": ["Products"],
"x-mint": {
"metadata": {
"title": "Resolve a canonical product",
"sidebarTitle": "Resolve a product",
"description": "Resolve a supplier-independent industrial product from its manufacturer and exact part number.",
"keywords": ["industrial product API", "manufacturer part number", "canonical product identity"],
"playground": "simple"
},
"content": "A product match does not confirm current stock, price, condition, or a seller's authority."
},
"parameters": [
{
"name": "manufacturer",
"in": "path",
"required": true,
"description": "Product manufacturer. Matching is case-insensitive.",
"schema": {
"type": "string"
},
"example": "siemens"
},
{
"name": "mpn",
"in": "path",
"required": true,
"description": "Exact manufacturer part number.",
"schema": {
"type": "string"
},
"example": "6ES7214-1AG40-0XB0"
}
],
"responses": {
"200": {
"description": "Canonical product identity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductResponse"
}
}
}
},
"404": {
"description": "No product matches that manufacturer and part number",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"SiteOverviewResponse": {
"type": "object",
"required": ["data", "links"],
"properties": {
"data": {
"$ref": "#/components/schemas/SiteOverview"
},
"links": {
"$ref": "#/components/schemas/SiteLinks"
}
},
"additionalProperties": false
},
"SiteOverview": {
"type": "object",
"required": ["name", "title", "description", "mission", "currentFocus", "releaseState", "authorityBoundary", "capabilities"],
"properties": {
"name": { "type": "string" },
"title": { "type": "string" },
"description": { "type": "string" },
"mission": { "type": "string" },
"currentFocus": { "type": "string" },
"releaseState": { "type": "string" },
"authorityBoundary": { "type": "string" },
"capabilities": {
"type": "array",
"items": { "type": "string" }
}
},
"additionalProperties": false
},
"SiteLinks": {
"type": "object",
"required": ["product", "vision", "insights", "onboarding"],
"properties": {
"product": { "type": "string", "format": "uri" },
"vision": { "type": "string", "format": "uri" },
"insights": { "type": "string", "format": "uri" },
"onboarding": { "type": "string", "format": "uri" }
},
"additionalProperties": false
},
"InsightListResponse": {
"type": "object",
"required": ["data", "meta"],
"properties": {
"data": {
"type": "array",
"items": { "$ref": "#/components/schemas/InsightSummary" }
},
"meta": {
"type": "object",
"required": ["total"],
"properties": {
"total": { "type": "integer", "minimum": 0 }
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"InsightSummary": {
"type": "object",
"required": ["slug", "title", "dek", "category", "publishedAt", "updatedAt", "readingMinutes", "proof", "url", "apiUrl"],
"properties": {
"slug": { "type": "string" },
"title": { "type": "string" },
"dek": { "type": "string" },
"category": { "type": "string" },
"publishedAt": { "type": "string", "format": "date" },
"updatedAt": { "type": "string", "format": "date" },
"readingMinutes": { "type": "integer", "minimum": 1 },
"proof": { "type": "string" },
"url": { "type": "string", "format": "uri" },
"apiUrl": { "type": "string", "format": "uri" }
},
"additionalProperties": false
},
"InsightResponse": {
"type": "object",
"required": ["data"],
"properties": {
"data": { "$ref": "#/components/schemas/Insight" }
},
"additionalProperties": false
},
"Insight": {
"allOf": [
{ "$ref": "#/components/schemas/InsightSummaryCore" },
{
"type": "object",
"required": ["status", "author", "featured", "blocks", "sources", "url"],
"properties": {
"status": { "const": "published" },
"author": { "type": "string" },
"featured": { "type": "boolean" },
"blocks": {
"type": "array",
"items": { "$ref": "#/components/schemas/InsightBlock" }
},
"sources": {
"type": "array",
"items": { "$ref": "#/components/schemas/InsightSource" }
},
"url": { "type": "string", "format": "uri" }
}
}
]
},
"InsightSummaryCore": {
"type": "object",
"required": ["slug", "title", "dek", "category", "publishedAt", "updatedAt", "readingMinutes", "proof"],
"properties": {
"slug": { "type": "string" },
"title": { "type": "string" },
"dek": { "type": "string" },
"category": { "type": "string" },
"publishedAt": { "type": "string", "format": "date" },
"updatedAt": { "type": "string", "format": "date" },
"readingMinutes": { "type": "integer", "minimum": 1 },
"proof": { "type": "string" }
}
},
"InsightBlock": {
"oneOf": [
{
"type": "object",
"required": ["type", "text"],
"properties": {
"type": { "enum": ["paragraph", "heading"] },
"text": { "type": "string" }
}
},
{
"type": "object",
"required": ["type", "items"],
"properties": {
"type": { "const": "list" },
"items": { "type": "array", "items": { "type": "string" } }
}
},
{
"type": "object",
"required": ["type", "label", "text"],
"properties": {
"type": { "const": "callout" },
"label": { "type": "string" },
"text": { "type": "string" }
}
}
]
},
"InsightSource": {
"type": "object",
"required": ["label", "url", "evidenceDate", "authority"],
"properties": {
"label": { "type": "string" },
"url": { "type": "string", "format": "uri" },
"evidenceDate": { "type": "string", "format": "date" },
"authority": { "type": "string" }
},
"additionalProperties": false
},
"ProductResponse": {
"type": "object",
"required": ["data", "links"],
"properties": {
"data": { "$ref": "#/components/schemas/Product" },
"links": {
"type": "object",
"additionalProperties": { "type": "string", "format": "uri" }
}
},
"additionalProperties": false
},
"Product": {
"type": "object",
"required": ["id", "object", "market", "manufacturer", "manufacturerPartNumber", "name", "identifiers", "verification"],
"properties": {
"id": { "type": "string", "pattern": "^prd_[a-z0-9]+$" },
"object": { "const": "product" },
"market": {
"type": "object",
"required": ["id", "name"],
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
}
},
"manufacturer": {
"type": "object",
"required": ["id", "name"],
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
}
},
"manufacturerPartNumber": { "type": "string" },
"name": { "type": "string" },
"description": { "type": "string" },
"identifiers": {
"type": "array",
"items": {
"type": "object",
"required": ["scheme", "value"],
"properties": {
"scheme": { "type": "string" },
"value": { "type": "string" }
}
}
},
"classification": { "type": "object" },
"physical": { "type": "object" },
"verification": {
"type": "object",
"required": ["status", "evidenceAsOf"],
"properties": {
"status": { "type": "string" },
"evidenceAsOf": { "type": "string", "format": "date" }
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"Problem": {
"type": "object",
"required": ["type", "title", "status", "detail"],
"properties": {
"type": { "type": "string", "format": "uri-reference" },
"title": { "type": "string" },
"status": { "type": "integer", "minimum": 400, "maximum": 599 },
"code": { "type": "string" },
"detail": { "type": "string" },
"retryable": { "type": "boolean" }
}
}
}
}
}