{"openapi":"3.1.0","info":{"title":"Material Progress API","version":"1.0.0","description":"Published articles, evidence, relationships and authorized reference collections. No public draft access."},"servers":[{"url":"https://materialprogress.io"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ArticleContent":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"headline":{"type":"string","minLength":5,"maxLength":180},"dek":{"type":"string","minLength":10,"maxLength":700},"category":{"type":"string","enum":["Technology","Audio","Cameras","Watches","Style","Travel","Outdoors","Home","Coffee","Tools","Grooming"]},"byline":{"type":"string","minLength":1,"maxLength":100},"sections":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"heading":{"type":"string","maxLength":150},"text":{"type":"string","minLength":1,"maxLength":15000}},"required":["heading","text"]}},"price_text":{"default":"","type":"string","maxLength":150},"availability":{"default":"","type":"string","maxLength":500},"announced_at":{"default":"","type":"string","maxLength":40},"hero":{"type":"object","properties":{"url":{"anyOf":[{"type":"string","maxLength":3000,"format":"uri"},{"type":"string","const":""}]},"alt":{"type":"string","minLength":5,"maxLength":500},"credit":{"type":"string","minLength":1,"maxLength":300},"license_url":{"default":"","anyOf":[{"type":"string","maxLength":3000,"format":"uri"},{"type":"string","const":""}]},"credit_url":{"default":"","anyOf":[{"type":"string","maxLength":3000,"format":"uri"},{"type":"string","const":""}]},"rights_basis":{"type":"string","maxLength":2000},"permission_reference":{"type":"string","maxLength":2000},"commercial_allowed":{"type":"boolean"},"approved":{"type":"boolean"}},"required":["url","alt","credit","rights_basis","permission_reference","commercial_allowed","approved"]},"sources":{"maxItems":30,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","maxLength":3000,"format":"uri"},"title":{"type":"string","minLength":1,"maxLength":300},"publisher":{"type":"string","minLength":1,"maxLength":200},"excerpt":{"default":"","type":"string","maxLength":500},"rights_basis":{"type":"string","minLength":1,"maxLength":2000}},"required":["id","url","title","publisher","rights_basis"]}},"claims":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"kind":{"type":"string","enum":["manufacturer_claim","verified_spec","external_observation","editorial_interpretation"]},"source_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"evidence":{"type":"string","maxLength":3000},"reviewed":{"type":"boolean"}},"required":["text","kind","source_id","evidence","reviewed"]}},"entities":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":120},"kind":{"type":"string","enum":["product","brand","designer","category","material","design_trait","use_case","audience","occasion"]},"relation":{"type":"string","maxLength":100},"explanation":{"type":"string","minLength":1,"maxLength":1000},"epistemic_type":{"type":"string","enum":["fact","editorial","inferred"]},"source_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["id","name","kind","relation","explanation","epistemic_type","source_id"]}},"intents":{"maxItems":30,"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":500},"explanation":{"type":"string","minLength":1,"maxLength":1000}},"required":["question","explanation"]}},"related":{"maxItems":30,"type":"array","items":{"type":"object","properties":{"article_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"explanation":{"type":"string","minLength":1,"maxLength":1000},"epistemic_type":{"type":"string","enum":["fact","editorial","inferred"]},"source_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["article_id","explanation","epistemic_type","source_id"]}},"commercial_type":{"type":"string","enum":["editorial","affiliate","sponsored"]},"advertiser":{"default":"","type":"string","maxLength":200},"campaign":{"default":"","type":"string","maxLength":200},"disclosure":{"default":"","type":"string","maxLength":1000},"cta_url":{"anyOf":[{"type":"string","maxLength":3000,"format":"uri"},{"type":"string","const":""}]},"cta_label":{"default":"Visit the maker","type":"string","maxLength":100},"review":{"type":"object","properties":{"accuracy":{"type":"boolean"},"rights":{"type":"boolean"},"no_hands_on_implication":{"type":"boolean"},"audience_fit":{"type":"boolean"},"originality":{"type":"boolean"}},"required":["accuracy","rights","no_hands_on_implication","audience_fit","originality"]},"is_fixture":{"default":false,"type":"boolean"},"generation":{"type":"object","properties":{"model":{"type":"string"},"prompt_version":{"type":"string"},"created_at":{"type":"string"}},"required":["model","prompt_version","created_at"]}},"required":["headline","dek","category","byline","sections","hero","sources","claims","entities","intents","related","commercial_type","cta_url","review"]},"CollectionInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":150},"description":{"default":"","type":"string","maxLength":2000},"visibility":{"default":"private","type":"string","enum":["private","public"]},"items":{"default":[],"maxItems":100,"type":"array","items":{"type":"object","properties":{"article_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"note":{"type":"string","maxLength":2000}},"required":["article_id","note"]}}},"required":["title"]}}},"paths":{"/api/v1/articles":{"get":{"summary":"Search published articles","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}},"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"entity","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"offset","in":"query","schema":{"type":"string"}}]}},"/api/v1/articles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a published article","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/articles/{id}/related":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Follow sourced or editorial relationships","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/collections":{"get":{"summary":"List owned collections","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}},"post":{"summary":"Create a collection","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":150},"description":{"default":"","type":"string","maxLength":2000},"visibility":{"default":"private","type":"string","enum":["private","public"]},"items":{"default":[],"maxItems":100,"type":"array","items":{"type":"object","properties":{"article_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"note":{"type":"string","maxLength":2000}},"required":["article_id","note"]}}},"required":["title"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/collections/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a public or owned collection","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}},"patch":{"summary":"Update an owned collection with revision","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":150},"description":{"default":"","type":"string","maxLength":2000},"visibility":{"default":"private","type":"string","enum":["private","public"]},"items":{"default":[],"maxItems":100,"type":"array","items":{"type":"object","properties":{"article_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"note":{"type":"string","maxLength":2000}},"required":["article_id","note"]}}},"required":["title"]},{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","minimum":1}}}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/editorial/intake":{"post":{"summary":"Submit permitted source material","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","title","publisher","text","reason","rights_basis"],"properties":{"url":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"text":{"type":"string"},"reason":{"type":"string"},"rights_basis":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/editorial/articles":{"get":{"summary":"List working drafts","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/editorial/articles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read working draft","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}},"patch":{"summary":"Save working revision","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content","revision"],"properties":{"revision":{"type":"integer"},"content":{"$ref":"#/components/schemas/ArticleContent"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/editorial/articles/{id}/submit":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"submit an exact saved revision","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/editorial/articles/{id}/publish":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"publish an exact saved revision","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}},"/api/v1/editorial/articles/{id}/archive":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"archive an exact saved revision","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"JSON error with error.code and error.message"},"401":{"description":"JSON error with error.code and error.message"},"403":{"description":"JSON error with error.code and error.message"},"404":{"description":"JSON error with error.code and error.message"},"409":{"description":"JSON error with error.code and error.message"},"422":{"description":"JSON error with error.code and error.message"},"429":{"description":"JSON error with error.code and error.message"},"503":{"description":"JSON error with error.code and error.message"}}}}}}