{"openapi":"3.1.0","info":{"title":"The True Tree Intelligence API","version":"2026-07-30","description":"Versioned access to derived, source-linked event intelligence. The API does not redistribute news full text or unlicensed images.","contact":{"email":"privacy@thetruetree.com"},"license":{"name":"Commercial license required","url":"https://localhost:3000/developers#license"}},"servers":[{"url":"https://localhost:3000/v1","description":"Production and sandbox keys share the same endpoint."}],"security":[{"bearerAuth":[]}],"paths":{"/topics":{"get":{"summary":"List entitled topics","operationId":"listTopics","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/$defs/TopicList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"403":{"description":"Missing scope or topic entitlement","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"409":{"description":"Topic is configured but not active","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"429":{"description":"Rate or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}}}}},"/events":{"get":{"summary":"List published events","operationId":"listEvents","parameters":[{"name":"topic","in":"query","required":true,"schema":{"type":"string","example":"news"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/$defs/EventList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"403":{"description":"Missing scope or topic entitlement","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"409":{"description":"Topic is configured but not active","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"429":{"description":"Rate or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}}}}},"/events/{id}":{"get":{"summary":"Get one published event and its source links","operationId":"getEvent","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"topic","in":"query","required":true,"schema":{"type":"string","example":"news"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/$defs/EventDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"403":{"description":"Missing scope or topic entitlement","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"409":{"description":"Topic is configured but not active","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"429":{"description":"Rate or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}}}}},"/updates":{"get":{"summary":"Read incremental event updates and correction notices","operationId":"listUpdates","parameters":[{"name":"topic","in":"query","required":true,"schema":{"type":"string","example":"news"}},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/$defs/UpdateList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"403":{"description":"Missing scope or topic entitlement","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"409":{"description":"Topic is configured but not active","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"429":{"description":"Rate or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}}}}},"/status":{"get":{"summary":"Public dataset freshness and coverage status","operationId":"getStatus","security":[],"responses":{"200":{"description":"Service status","content":{"application/json":{"schema":{"$ref":"#/$defs/ServiceStatus"}}}},"503":{"description":"Status unavailable","content":{"application/json":{"schema":{"$ref":"#/$defs/Problem"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"tt_live_* or tt_test_*"}}},"$defs":{"Envelope":{"type":"object","required":["apiVersion","requestId","environment","data"],"properties":{"apiVersion":{"type":"string","const":"2026-07-30"},"requestId":{"type":"string","format":"uuid"},"environment":{"type":"string","enum":["test","live"]},"data":{}}},"TopicList":{"allOf":[{"$ref":"#/$defs/Envelope"}]},"EventList":{"allOf":[{"$ref":"#/$defs/Envelope"}]},"EventDetail":{"allOf":[{"$ref":"#/$defs/Envelope"}]},"UpdateList":{"allOf":[{"$ref":"#/$defs/Envelope"}]},"ServiceStatus":{"type":"object","required":["apiVersion","data"],"properties":{"apiVersion":{"type":"string"},"data":{"type":"object"}}},"Problem":{"type":"object","required":["type","title","status","detail","requestId"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}}