{"openapi":"3.1.0","info":{"title":"BrandSource public research API","version":"1.0.0","description":"Read-only brand discovery and scoped evidence. Directory fields can be incomplete or imported. Briefs and comparisons contain individually reviewed evidence records, not every legacy profile field. Crawler requests do not prove indexing or citations."},"servers":[{"url":"https://brandsource.ai"}],"paths":{"/api/brands":{"get":{"operationId":"searchBrands","summary":"Search public brands by name, category or website","parameters":[{"name":"search","in":"query","description":"Substring search, including a domain such as joinappear.com.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Category slug.","schema":{"type":"string"}},{"name":"page","in":"query","description":"One-based page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Number of records per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}}],"responses":{"200":{"description":"Read brands and pagination.hasMore; increment page while true.","content":{"application/json":{"schema":{"type":"object","required":["brands","pagination"],"properties":{"brands":{"type":"array","items":{"type":"object"}},"pagination":{"type":"object","required":["page","limit","total","totalPages","hasMore"],"properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"500":{"description":"Temporary search failure.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/brands/{slug}":{"get":{"operationId":"getBrand","summary":"Read the public profile, including legacy fields and source links","parameters":[{"name":"slug","in":"path","required":true,"description":"The slug returned by brand search; do not guess from the company name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Public profile; missing fields remain unknown.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Public record not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Temporary profile failure.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Temporary failure. Retry later; do not interpret as missing evidence.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/brands/{slug}/json-ld":{"get":{"operationId":"getBrandStructuredData","summary":"Read structured profile assertions","parameters":[{"name":"slug","in":"path","required":true,"description":"The slug returned by brand search; do not guess from the company name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Profile metadata and assertions; confidence is not independent verification.","content":{"application/ld+json":{"schema":{"type":"array","items":{"type":"object"}}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Public record not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Temporary structured data failure.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Temporary failure. Retry later; do not interpret as missing evidence.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/brands/{slug}/brief":{"get":{"operationId":"getResearchBrief","summary":"Read individually reviewed evidence with scope and unresolved questions","parameters":[{"name":"slug","in":"path","required":true,"description":"The slug returned by brand search; do not guess from the company name.","schema":{"type":"string"}},{"name":"format","in":"query","description":"Response format.","schema":{"type":"string","enum":["json","markdown"],"default":"json"}}],"responses":{"200":{"description":"Partial evidence coverage is explicit. Preserve source attribution, status, scope and dates.","content":{"application/json":{"schema":{"type":"object"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Public record not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Temporary failure. Retry later; do not interpret as missing evidence.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/brand-comparison":{"get":{"operationId":"compareBrands","summary":"Compare sourced claims for two or three brands","parameters":[{"name":"brands","in":"query","description":"Two or three distinct, comma-separated slugs returned by search.","schema":{"type":"string","example":"appear,the-rank-collective"},"required":true}],"responses":{"200":{"description":"Source-backed comparison. Empty or unresolved cells mean unknown.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Public record not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Temporary failure. Retry later; do not interpret as missing evidence.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/stats":{"get":{"operationId":"getDirectoryStatistics","summary":"Read dated directory and crawler counts","responses":{"200":{"description":"brandCount is published profiles; crawlerVisits is recorded requests over 30 days. sampledAt is the snapshot time.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Temporary failure. Retry later; do not interpret as missing evidence.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/rankings":{"get":{"operationId":"getCrawlerRankings","summary":"Read dated rankings by recorded crawler requests","responses":{"200":{"description":"Not a quality ranking or proof of indexing, training or citation. generatedAt is the snapshot time.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Temporary report failure.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}}}