{"openapi":"3.1.0","info":{"title":"MADO public reference API","version":"1.0.0","description":"Read-only public references in Arabic and English. No user, billing or trading access. See /en/developers for MCP connection and limits."},"servers":[{"url":"https://madoinfra.com"}],"paths":{"/api/knowledge":{"get":{"operationId":"getMadoPublicKnowledge","summary":"Search or read MADO published references","description":"No authentication for already-public content. 60 requests/minute per trusted IP, with a shared public-traffic cap of 120/minute. Honor Retry-After on 429/503. Use id or query, never both. Unknown parameters are rejected. Responses include canonical sources and retrieval time; unsupported questions must not be answered by invention.","parameters":[{"name":"lang","in":"query","description":"Reference language","schema":{"type":"string","enum":["ar","en"],"default":"ar"}},{"name":"id","in":"query","description":"An exact reference ID from the index; excludes query","schema":{"type":"string","pattern":"^[a-z-]{1,60}$"}},{"name":"query","in":"query","description":"Bounded lexical search of public references; excludes id","schema":{"type":"string","minLength":2,"maxLength":160}},{"name":"limit","in":"query","description":"Maximum search results","schema":{"type":"integer","minimum":1,"maximum":5,"default":5}}],"responses":{"200":{"description":"Reference, bounded search results, or reference index. First-party facts, not independent certification.","content":{"application/json":{"schema":{"type":"object","required":["data","sourceType","retrievedAt","policy"],"properties":{"data":{"type":"object","additionalProperties":true},"sourceType":{"type":"string","const":"first_party_public_reference"},"retrievedAt":{"type":"string","format":"date-time"},"policy":{"type":"string"}}}}}},"400":{"description":"Structured error; no secrets or account data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","additionalProperties":true}}}}}},"403":{"description":"Structured error; no secrets or account data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","additionalProperties":true}}}}}},"404":{"description":"Structured error; no secrets or account data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","additionalProperties":true}}}}}},"429":{"description":"Structured error; no secrets or account data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","additionalProperties":true}}}}}},"503":{"description":"Structured error; no secrets or account data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","additionalProperties":true}}}}}}}}}}}