{"info":{"title":"Temso Public API","version":"1.0.0","description":"REST API for exporting Temso project analytics, responses, mentions, sources, and traffic data."},"servers":[{"url":"https://api.temso.ai/v1","description":"Production"}],"openapi":"3.1.1","paths":{"/projects":{"get":{"operationId":"projects.list","summary":"List projects available to this API key","tags":["Projects"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/prompts/responses":{"get":{"operationId":"prompts.responses","summary":"Get raw AI responses","tags":["Responses"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt, x-ai/grok-search","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt,x-ai/grok-search"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter by branded status","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs — limits to responses where at least one of these brands was mentioned"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"responseId":{"type":"string"},"promptText":{"type":"string"},"model":{"type":"string"},"country":{"type":"string"},"language":{"type":"string"},"presence":{"type":"number"},"totalSources":{"type":"number"},"createdAt":{"type":"string"},"promptType":{"type":"string"},"isBranded":{"type":"boolean"},"keywords":{"type":"string"}},"required":["responseId","promptText","model","country","language","presence","totalSources","createdAt","promptType","isBranded","keywords"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/brands":{"get":{"operationId":"brands.list","summary":"List accepted brands (own brand + competitors) for a project","tags":["Brands"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string"},"brandName":{"type":"string"},"isOwnBrand":{"type":"boolean"},"website":{"type":"string"}},"required":["brandId","brandName","isOwnBrand","website"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/brands/mentions":{"get":{"operationId":"brands.mentions","summary":"Get raw brand mentions","tags":["Mentions"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt, x-ai/grok-search","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt,x-ai/grok-search"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter by branded status","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"responseId":{"type":"string"},"brandName":{"type":"string"},"isOwnBrand":{"type":"boolean"},"model":{"type":"string"},"position":{"type":"number"},"sentiment":{"type":"string"},"perception":{"type":"string"},"createdAt":{"type":"string"}},"required":["responseId","brandName","isOwnBrand","model","position","sentiment","perception","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources":{"get":{"operationId":"sources.list","summary":"Get raw source citations","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt, x-ai/grok-search","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt,x-ai/grok-search"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter by branded status","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs — limits to sources tied to responses where at least one of these brands was mentioned"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"responseId":{"type":"string"},"url":{"type":"string"},"domain":{"type":"string"},"position":{"type":"number"},"type":{"type":"string"},"domainRank":{"anyOf":[{"type":"number"},{"type":"null"}]},"urlRank":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["responseId","url","domain","position","type","domainRank","urlRank","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/visibility":{"get":{"operationId":"analytics.visibility","summary":"Get visibility score over time","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt, x-ai/grok-search","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt,x-ai/grok-search"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter by branded status","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"visibilityScore":{"type":"number"},"totalResponses":{"type":"number"},"totalMentions":{"type":"number"}},"required":["date","visibilityScore","totalResponses","totalMentions"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/share-of-voice":{"get":{"operationId":"analytics.shareOfVoice","summary":"Get share of voice over time (per brand per day)","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt, x-ai/grok-search","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt,x-ai/grok-search"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter by branded status","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"brandName":{"type":"string"},"isOwnBrand":{"type":"boolean"},"mentions":{"type":"number"}},"required":["date","brandName","isOwnBrand","mentions"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/brand-rankings":{"get":{"operationId":"analytics.brandRankings","summary":"Get per-brand performance (visibility, share of voice, mentions, responses)","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt, x-ai/grok-search","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt,x-ai/grok-search"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter by branded status","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string"},"brandName":{"type":"string"},"isOwnBrand":{"type":"boolean"},"avgVisibilityScore":{"type":"number"},"avgPresence":{"type":"number"},"totalMentions":{"type":"number"},"totalResponses":{"type":"number"},"shareOfVoice":{"type":"number"}},"required":["brandId","brandName","isOwnBrand","avgVisibilityScore","avgPresence","totalMentions","totalResponses","shareOfVoice"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/traffic/ingest/worker/{sourceId}":{"post":{"operationId":"traffic.ingestWorker","summary":"Ingest a batch of request events from a Cloudflare Worker","tags":["Traffic"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"The traffic source ID assigned during setup"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"integer"},"events":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"integer","description":"Unix milliseconds when the request was observed at the edge"},"ua":{"type":"string","maxLength":512},"method":{"type":"string","maxLength":8},"url":{"type":"string","maxLength":2048},"status":{"type":"integer","minimum":100,"maximum":599},"country":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}]},"asn":{"anyOf":[{"type":"integer"},{"type":"null"}]},"referer":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Raw client IP. Hashed and prefix-anonymized server-side, then discarded."}},"required":["ts","ua","method","url","status","country","asn","referer"]},"minItems":1,"maxItems":500}},"required":["timestamp","events"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"number"},"dropped":{"type":"number"},"idempotent":{"type":"boolean"},"revoked":{"type":"boolean"}},"required":["accepted","dropped","idempotent","revoked"]}}}}}}}}}