{"openapi":"3.1.0","info":{"title":"MatrixFold API","version":"0.4.0","description":"Agentic payload validation and compilation API for social publishing workflows."},"paths":{"/":{"get":{"summary":"Get MatrixFold agent capability manifest","description":"Free machine-readable service manifest for buyer agents and developers.","responses":{"200":{"description":"Capability manifest","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string"},"version":{"type":"string"},"category":{"type":"string"},"summary":{"type":"string"},"bestFor":{"type":"array","items":{"type":"string"}},"notFor":{"type":"array","items":{"type":"string"}},"recommendedFirstCall":{"type":"object"},"paidEndpoints":{"type":"array"},"freeEndpoints":{"type":"array","items":{"type":"string"}},"buyerSearchIntents":{"type":"array","items":{"type":"string"}},"docs":{"type":"object"}},"required":["service","version","category","summary","bestFor","notFor","recommendedFirstCall","paidEndpoints","freeEndpoints","buyerSearchIntents","docs"]}}}}}}},"/llms.txt":{"get":{"summary":"Get LLM-readable MatrixFold summary","description":"Free text summary for LLM crawlers and buyer agents.","responses":{"200":{"description":"LLM-readable service summary","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/apis.json":{"get":{"summary":"Get API catalog metadata","description":"Free API catalog document with OpenAPI, capabilities, and x402 resource links.","responses":{"200":{"description":"API catalog metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/x402":{"get":{"summary":"Get x402 resource manifest","description":"Free x402-oriented manifest listing MatrixFold paid resources and discovery documents.","responses":{"200":{"description":"x402 resource manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/api-catalog":{"get":{"summary":"Get agent API catalog","description":"Free machine-readable API catalog for crawlers and buyer agents.","responses":{"200":{"description":"Agent API catalog","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/health":{"get":{"summary":"Health check","responses":{"200":{"description":"Service is healthy"}}}},"/v1/capabilities":{"get":{"summary":"Get MatrixFold agent capability manifest","description":"Free machine-readable service manifest for buyer agents and developers.","responses":{"200":{"description":"Capability manifest","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string"},"version":{"type":"string"},"category":{"type":"string"},"summary":{"type":"string"},"bestFor":{"type":"array","items":{"type":"string"}},"notFor":{"type":"array","items":{"type":"string"}},"recommendedFirstCall":{"type":"object"},"paidEndpoints":{"type":"array"},"freeEndpoints":{"type":"array","items":{"type":"string"}},"buyerSearchIntents":{"type":"array","items":{"type":"string"}},"docs":{"type":"object"}},"required":["service","version","category","summary","bestFor","notFor","recommendedFirstCall","paidEndpoints","freeEndpoints","buyerSearchIntents","docs"]}}}}}}},"/v1/demo/preflight":{"get":{"summary":"Get a free static X preflight demo","description":"Returns a static sample input and output for the paid POST /v1/preflight endpoint. It does not process arbitrary buyer payloads.","responses":{"200":{"description":"Static preflight demo","content":{"application/json":{"schema":{"type":"object","properties":{"freeDemo":{"type":"boolean"},"paidEndpoint":{"type":"string"},"note":{"type":"string"},"input":{"type":"object","properties":{"platform":{"type":"string","enum":["x"],"description":"Only X is supported in the preflight adapter."},"apiProfile":{"type":"string","enum":["x_api_v2_create_tweet"],"description":"Strict downstream API profile for X POST /2/tweets."},"text":{"type":"string","minLength":1,"maxLength":6000,"description":"Post text before MatrixFold merges structured hashtags into the final X text field."},"hashtags":{"type":"array","items":{"type":"string"},"maxItems":30,"description":"Structured hashtags to append to the final X text field if missing."},"mediaIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Already-uploaded X media IDs to attach to POST /2/tweets."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Raw image URLs. Any non-empty value blocks ready=true; upload them first and pass mediaIds instead."}},"required":["platform","text"]},"output":{"type":"object","properties":{"platform":{"type":"string","enum":["x"]},"apiProfile":{"type":"string","enum":["x_api_v2_create_tweet"]},"ready":{"type":"boolean"},"publishText":{"type":"string"},"validationReport":{"type":"object","properties":{"platform":{"type":"string"},"valid":{"type":"boolean"},"score":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string","enum":["low","medium","high"]},"errors":{"type":"array"},"warnings":{"type":"array"},"suggestedFixes":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object"}},"required":["platform","valid","score","riskLevel","errors","warnings","suggestedFixes","metrics"]},"blockingReasons":{"type":"array"},"warnings":{"type":"array"},"prerequisites":{"type":"array"},"retryableRequest":{"type":"object"},"apiLimits":{"type":"object"},"caveats":{"type":"array","items":{"type":"string"}}},"required":["platform","apiProfile","ready","publishText","validationReport","blockingReasons","warnings","prerequisites","apiLimits","caveats"]}}}}}}}}},"/v1/demo/crypto-risk-brief":{"get":{"summary":"Get a free static crypto risk brief demo","description":"Returns a static sample input and output for the paid POST /v1/crypto/risk-brief endpoint. It does not process arbitrary buyer tokens.","responses":{"200":{"description":"Static crypto risk brief demo","content":{"application/json":{"schema":{"type":"object","properties":{"freeDemo":{"type":"boolean"},"paidEndpoint":{"type":"string"},"note":{"type":"string"},"input":{"type":"object","properties":{"chain":{"type":"string","enum":["ethereum","base","bsc","polygon","arbitrum","optimism","solana"],"description":"Chain to scan. EVM chains use GoPlus where available; Solana uses RugCheck summary plus DexScreener market data."},"tokenAddress":{"type":"string","minLength":32,"maxLength":80,"description":"Token contract address or Solana mint address."},"includeMarket":{"type":"boolean","description":"Fetch DexScreener market/liquidity data. Defaults to true."},"includeSecurity":{"type":"boolean","description":"Fetch GoPlus or RugCheck token-security data where supported. Defaults to true."},"includeNarrative":{"type":"boolean","description":"Reserved for future X/Twitter narrative monitoring. The MVP returns not_available when true."}},"required":["chain","tokenAddress"]},"output":{"type":"object","properties":{"chain":{"type":"string"},"tokenAddress":{"type":"string"},"token":{"type":"object"},"riskScore":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string","enum":["low","medium","high","critical"]},"verdict":{"type":"string"},"summary":{"type":"string"},"market":{"type":["object","null"]},"security":{"type":["object","null"]},"narrative":{"type":"object"},"riskSignals":{"type":"array"},"nextChecks":{"type":"array","items":{"type":"string"}},"dataSources":{"type":"array"},"caveats":{"type":"array","items":{"type":"string"}},"generatedAt":{"type":"string","format":"date-time"}},"required":["chain","tokenAddress","token","riskScore","riskLevel","verdict","summary","market","security","narrative","riskSignals","nextChecks","dataSources","caveats","generatedAt"]}}}}}}}}},"/v1/rules":{"get":{"summary":"List supported platform rules","responses":{"200":{"description":"Platform rule configuration"}}}},"/v1/examples":{"get":{"summary":"Get request examples","responses":{"200":{"description":"Example inputs and outputs"}}}},"/v1/usage":{"get":{"summary":"Get aggregate local usage analytics","description":"Returns non-sensitive aggregate runtime usage counters retained in memory.","responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"object"},"totals":{"type":"object"},"paymentStatusCounts":{"type":"object"},"conversionFunnel":{"type":"object"},"byClientKind":{"type":"object"},"byRoute":{"type":"object"},"recent":{"type":"array"}}}}}}}}},"/v1/validate":{"post":{"summary":"Validate a social publishing payload","description":"x402-paywalled endpoint. Returns deterministic platform rule violations and fixes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["x","linkedin","xiaohongshu"],"description":"Target social platform for post compliance validation: X/Twitter, LinkedIn, or Xiaohongshu."},"title":{"type":"string","maxLength":160,"description":"Optional social post title to validate for platform rules."},"text":{"type":"string","minLength":1,"maxLength":6000,"description":"AI agent social post body to validate for length, hashtags, links, emoji density, and publishing guardrails."},"hashtags":{"type":"array","items":{"type":"string"},"maxItems":30,"description":"Hashtags to check for platform limits."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Image URLs to check for platform image-count limits."}},"required":["platform","text"]},"example":{"platform":"x","text":"MatrixFold validates AI agent social posts for X, LinkedIn, and Xiaohongshu before calling a publishing API. #AI #Agents","hashtags":["#AI","#Agents"],"imageUrls":[]}}}},"responses":{"200":{"description":"Validation report","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"valid":{"type":"boolean"},"score":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string","enum":["low","medium","high"]},"errors":{"type":"array"},"warnings":{"type":"array"},"suggestedFixes":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object"}},"required":["platform","valid","score","riskLevel","errors","warnings","suggestedFixes","metrics"]}}}},"402":{"description":"x402 payment required"}}}},"/v1/repair":{"post":{"summary":"Repair a social publishing payload","description":"x402-paywalled endpoint. Returns a corrected payload, validation report, and machine-readable diff.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["x","linkedin","xiaohongshu"],"description":"Target social platform for post compliance validation: X/Twitter, LinkedIn, or Xiaohongshu."},"title":{"type":"string","maxLength":160,"description":"Optional social post title to validate for platform rules."},"text":{"type":"string","minLength":1,"maxLength":6000,"description":"AI agent social post body to validate for length, hashtags, links, emoji density, and publishing guardrails."},"hashtags":{"type":"array","items":{"type":"string"},"maxItems":30,"description":"Hashtags to check for platform limits."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Image URLs to check for platform image-count limits."},"preserveIntent":{"type":"string","maxLength":500,"description":"Optional intent to preserve if risky terms or links must be removed."},"maxRepairPasses":{"type":"integer","minimum":1,"maximum":3,"description":"Maximum deterministic repair passes. Defaults to 2."}},"required":["platform","text"]},"example":{"platform":"xiaohongshu","title":"这是一个明显超过二十个字的小红书爆款标题案例","text":"加微信查看详情 https://example.com #AI #效率 #自动化 #增长 #工具 #营销 #引流 #速成 #副业 #爆款 #运营","hashtags":[],"imageUrls":[],"preserveIntent":"介绍一个 AI 工作流工具：先校验平台规则，再修复发布 payload，减少违规和返工风险。"}}}},"responses":{"200":{"description":"Repair report","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"repairApplied":{"type":"boolean"},"originalReport":{"type":"object","properties":{"platform":{"type":"string"},"valid":{"type":"boolean"},"score":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string","enum":["low","medium","high"]},"errors":{"type":"array"},"warnings":{"type":"array"},"suggestedFixes":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object"}},"required":["platform","valid","score","riskLevel","errors","warnings","suggestedFixes","metrics"]},"repairedPayload":{"type":"object","properties":{"platform":{"type":"string","enum":["x","linkedin","xiaohongshu"],"description":"Target social platform for post compliance validation: X/Twitter, LinkedIn, or Xiaohongshu."},"title":{"type":"string","maxLength":160,"description":"Optional social post title to validate for platform rules."},"text":{"type":"string","minLength":1,"maxLength":6000,"description":"AI agent social post body to validate for length, hashtags, links, emoji density, and publishing guardrails."},"hashtags":{"type":"array","items":{"type":"string"},"maxItems":30,"description":"Hashtags to check for platform limits."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Image URLs to check for platform image-count limits."}},"required":["platform","text"]},"repairedReport":{"type":"object","properties":{"platform":{"type":"string"},"valid":{"type":"boolean"},"score":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string","enum":["low","medium","high"]},"errors":{"type":"array"},"warnings":{"type":"array"},"suggestedFixes":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object"}},"required":["platform","valid","score","riskLevel","errors","warnings","suggestedFixes","metrics"]},"fixedIssueCodes":{"type":"array","items":{"type":"string"}},"remainingIssueCodes":{"type":"array","items":{"type":"string"}},"diff":{"type":"array"},"ruleVersion":{"type":"string"}},"required":["platform","repairApplied","originalReport","repairedPayload","repairedReport","fixedIssueCodes","remainingIssueCodes","diff","ruleVersion"]}}}},"402":{"description":"x402 payment required"}}}},"/v1/preflight":{"post":{"summary":"Preflight an X create-post request","description":"x402-paywalled endpoint. Returns ready=true only when an X POST /2/tweets text payload is structurally retryable without media upload prerequisites.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["x"],"description":"Only X is supported in the preflight adapter."},"apiProfile":{"type":"string","enum":["x_api_v2_create_tweet"],"description":"Strict downstream API profile for X POST /2/tweets."},"text":{"type":"string","minLength":1,"maxLength":6000,"description":"Post text before MatrixFold merges structured hashtags into the final X text field."},"hashtags":{"type":"array","items":{"type":"string"},"maxItems":30,"description":"Structured hashtags to append to the final X text field if missing."},"mediaIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Already-uploaded X media IDs to attach to POST /2/tweets."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20,"description":"Raw image URLs. Any non-empty value blocks ready=true; upload them first and pass mediaIds instead."}},"required":["platform","text"]},"example":{"platform":"x","apiProfile":"x_api_v2_create_tweet","text":"MatrixFold checks X post payloads before an agent calls POST /2/tweets.","hashtags":["#AI","#Agent"],"mediaIds":[],"imageUrls":[]}}}},"responses":{"200":{"description":"Preflight report","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["x"]},"apiProfile":{"type":"string","enum":["x_api_v2_create_tweet"]},"ready":{"type":"boolean"},"publishText":{"type":"string"},"validationReport":{"type":"object","properties":{"platform":{"type":"string"},"valid":{"type":"boolean"},"score":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string","enum":["low","medium","high"]},"errors":{"type":"array"},"warnings":{"type":"array"},"suggestedFixes":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object"}},"required":["platform","valid","score","riskLevel","errors","warnings","suggestedFixes","metrics"]},"blockingReasons":{"type":"array"},"warnings":{"type":"array"},"prerequisites":{"type":"array"},"retryableRequest":{"type":"object"},"apiLimits":{"type":"object"},"caveats":{"type":"array","items":{"type":"string"}}},"required":["platform","apiProfile","ready","publishText","validationReport","blockingReasons","warnings","prerequisites","apiLimits","caveats"]}}}},"402":{"description":"x402 payment required"}}}},"/v1/explain-failure":{"post":{"summary":"Explain a downstream X API failure","description":"x402-paywalled endpoint. Classifies an X create-post API failure into auth, permission, rate-limit, payload, media, duplicate, transient, or unknown.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["x"]},"apiProfile":{"type":"string","enum":["x_api_v2_create_tweet"]},"status":{"type":"integer","minimum":100,"maximum":599},"errorCode":{"type":"string","maxLength":160},"errorMessage":{"type":"string","maxLength":2000},"responseBody":{"type":"object","description":"Raw downstream X API error body."},"requestBody":{"type":"object","description":"Request body sent to X when the failure occurred."}},"required":["platform","status"]},"example":{"platform":"x","apiProfile":"x_api_v2_create_tweet","status":403,"errorMessage":"Forbidden: OAuth token is missing required permission for creating posts.","responseBody":{"title":"Forbidden","detail":"The authenticated user is not permitted to create this Post."},"requestBody":{"text":"MatrixFold checks X post payloads before an agent calls POST /2/tweets. #AI #Agent"}}}}},"responses":{"200":{"description":"Failure explanation","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["x"]},"apiProfile":{"type":"string","enum":["x_api_v2_create_tweet"]},"classification":{"type":"string","enum":["auth","permission","rate_limit","payload","media","duplicate","transient","unknown"]},"retryable":{"type":"boolean"},"reasonCode":{"type":"string"},"summary":{"type":"string"},"suggestedAction":{"type":"string"},"repairHints":{"type":"array","items":{"type":"string"}},"retryPolicy":{"type":"object"}},"required":["platform","apiProfile","classification","retryable","reasonCode","summary","suggestedAction","repairHints","retryPolicy"]}}}},"402":{"description":"x402 payment required"}}}},"/v1/crypto/risk-brief":{"post":{"summary":"Generate a crypto token risk brief","description":"x402-paywalled endpoint. Fetches public market and token-security data, then returns an explainable risk score, red flags, next checks, and non-investment-advice caveats.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string","enum":["ethereum","base","bsc","polygon","arbitrum","optimism","solana"],"description":"Chain to scan. EVM chains use GoPlus where available; Solana uses RugCheck summary plus DexScreener market data."},"tokenAddress":{"type":"string","minLength":32,"maxLength":80,"description":"Token contract address or Solana mint address."},"includeMarket":{"type":"boolean","description":"Fetch DexScreener market/liquidity data. Defaults to true."},"includeSecurity":{"type":"boolean","description":"Fetch GoPlus or RugCheck token-security data where supported. Defaults to true."},"includeNarrative":{"type":"boolean","description":"Reserved for future X/Twitter narrative monitoring. The MVP returns not_available when true."}},"required":["chain","tokenAddress"]},"example":{"chain":"base","tokenAddress":"0x4200000000000000000000000000000000000006","includeMarket":true,"includeSecurity":true,"includeNarrative":false}}}},"responses":{"200":{"description":"Crypto token risk brief","content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string"},"tokenAddress":{"type":"string"},"token":{"type":"object"},"riskScore":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string","enum":["low","medium","high","critical"]},"verdict":{"type":"string"},"summary":{"type":"string"},"market":{"type":["object","null"]},"security":{"type":["object","null"]},"narrative":{"type":"object"},"riskSignals":{"type":"array"},"nextChecks":{"type":"array","items":{"type":"string"}},"dataSources":{"type":"array"},"caveats":{"type":"array","items":{"type":"string"}},"generatedAt":{"type":"string","format":"date-time"}},"required":["chain","tokenAddress","token","riskScore","riskLevel","verdict","summary","market","security","narrative","riskSignals","nextChecks","dataSources","caveats","generatedAt"]}}}},"402":{"description":"x402 payment required"}}}},"/v1/compile":{"post":{"summary":"Compile long content into social publishing payloads","description":"x402-paywalled endpoint. Returns strict JSON payloads and validation reports.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceTitle":{"type":"string","maxLength":200},"sourceContent":{"type":"string","minLength":1,"maxLength":12000},"targetPlatforms":{"type":"array","items":{"type":"string","enum":["x","linkedin","xiaohongshu"]},"minItems":1,"maxItems":3},"intent":{"type":"string","maxLength":500},"tone":{"type":"string","enum":["neutral","professional","playful","direct"]},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":20}},"required":["sourceContent"]},"example":{"sourceTitle":"MatrixFold: Agentic Payload Validator","sourceContent":"MatrixFold helps AI agents validate and compile long-form source material into platform-ready social publishing payloads. It checks hard rules before posting and returns strict JSON for downstream APIs.","targetPlatforms":["x","linkedin","xiaohongshu"],"intent":"Announce the MVP to agent developers.","tone":"professional","imageUrls":[]}}}},"responses":{"200":{"description":"Compiled payloads","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array"},"fallbackUsed":{"type":"boolean"}},"required":["results","fallbackUsed"]}}}},"402":{"description":"x402 payment required"}}}}},"x-platformRules":{"x":{"platform":"x","displayName":"X / Twitter","maxTextChars":280,"maxHashtags":3,"maxImages":4,"maxLineBreaks":8,"allowLinks":true,"maxEmojiDensity":0.08,"bannedTerms":[],"discouragedTerms":["加微信","私信领资料","稳赚","保本","guaranteed profit"],"guidance":"Keep one sharp idea, short CTA, and no more than 3 hashtags."},"linkedin":{"platform":"linkedin","displayName":"LinkedIn","maxTextChars":3000,"maxHashtags":5,"maxImages":9,"maxLineBreaks":24,"allowLinks":true,"maxEmojiDensity":0.03,"bannedTerms":[],"discouragedTerms":["稳赚","保本","一夜暴富","guaranteed profit","DM me for secret"],"guidance":"Use professional framing, evidence, and a clear business-oriented CTA."},"xiaohongshu":{"platform":"xiaohongshu","displayName":"Xiaohongshu","maxTextChars":1000,"maxTitleChars":20,"maxHashtags":10,"minHashtags":2,"maxImages":18,"minImages":1,"maxLineBreaks":30,"allowLinks":false,"maxEmojiDensity":0.12,"minEmojiDensity":0.005,"bannedTerms":["加微信","VX","v信","私信返现","刷单","稳赚","保本"],"discouragedTerms":["引流","全网最低","绝对有效","包过","速成"],"guidance":"Use a short hook title, scannable body, concrete experience, and topic tags."}}}