{"openapi":"3.1.0","info":{"title":"Takeover API","version":"1.0.0","description":"Event planning signals from Qloo taste data. Every response carries Qloo's attribution, which you must show wherever you display the data. The API comes with Enterprise: 60 requests a minute and 10000 a month per key (placeholders to confirm)."},"servers":[{"url":"https://takeover-fawn.vercel.app/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A workspace API key (tk_…), from Settings → API."}},"schemas":{"Attribution":{"type":"object","required":["source","text","url"],"properties":{"source":{"const":"Qloo"},"text":{"type":"string"},"url":{"type":"string"},"note":{"type":"string"}}},"Envelope":{"type":"object","required":["data","evidence","attribution","meta"],"properties":{"data":{"description":"The answer. Has status: done, choose (pick an entityId and ask again), none, queued, running or failed."},"evidence":{"description":"The Qloo requests behind the figures and how each figure is computed."},"attribution":{"$ref":"#/components/schemas/Attribution"},"meta":{"type":"object","properties":{"endpoint":{"type":"string"},"requestId":{"type":"string"},"mock":{"type":"boolean","description":"True only on sample-data deployments."},"qlooCalls":{"type":"integer"},"quota":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"},"resetsAt":{"type":"string","format":"date-time"}}}}}}},"Error":{"type":"object","required":["error","attribution"],"properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"attribution":{"$ref":"#/components/schemas/Attribution"}}}},"responses":{"Error":{"description":"An error, with the attribution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/overlap":{"get":{"summary":"Fan overlap","description":"How strongly each fanbase's fans over-index on the other (Qloo affinity both ways), and the cities where both are strong.","security":[{"bearer":[]}],"parameters":[{"name":"a","in":"query","required":true,"description":"First name: an artist, comedian, show, podcast, film or team.","schema":{"type":"string"}},{"name":"b","in":"query","required":true,"description":"Second name.","schema":{"type":"string"}},{"name":"aId","in":"query","required":false,"description":"Qloo entity id for a, from a previous choose answer.","schema":{"type":"string"}},{"name":"bId","in":"query","required":false,"description":"Qloo entity id for b.","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/fanbases/cities":{"get":{"summary":"Fanbase cities","description":"Where a fanbase is strongest, market by market, from Qloo heatmaps scored by the engine.","security":[{"bearer":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"The fanbase.","schema":{"type":"string"}},{"name":"entityId","in":"query","required":false,"description":"Qloo entity id, from a previous choose answer.","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/venues":{"get":{"summary":"Venue recommendations","description":"Who people in a city over-index on, by kind (music, comedy, podcast, brand): who to book there.","security":[{"bearer":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"A city name, e.g. Austin or Manchester, UK.","schema":{"type":"string"}},{"name":"kinds","in":"query","required":false,"description":"Comma-separated: music, comedy, podcast, brand. Default music,comedy.","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/brands/matches":{"get":{"summary":"Brand matches","description":"Talent, shows and podcasts a brand's fans over-index on, scored by the engine, and the brand's strongest cities.","security":[{"bearer":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"The brand.","schema":{"type":"string"}},{"name":"entityId","in":"query","required":false,"description":"Qloo entity id, from a previous choose answer.","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/plans":{"post":{"summary":"Create a plan (async)","description":"Runs the Takeover agent for a fanbase in the background and saves the plan to your workspace. Answers 202 with a job id; poll GET /plans/{planId}.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"The fanbase."},"entityId":{"type":"string","description":"Qloo entity id, to skip the name match."}}}}}},"responses":{"202":{"description":"The envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/plans/{id}":{"get":{"summary":"Get a plan","description":"The job's status (queued, running, failed) or, when done, the plan: partner, city, venue and sponsors with their scores, the brief and the outreach drafts.","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The planId from POST /plans.","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}}}}