{"openapi":"3.1.0","info":{"title":"Coherence API","version":"1.0.0","description":"Use every Coherence tool from your own systems. Requests act for one workspace and need an API key from Developers in the Coherence app. API access is included with Business licences.","termsOfService":"https://app.coherenceltd.com/legal/developer-terms","contact":{"name":"Coherence","email":"office@coherenceltd.com","url":"https://developers.coherenceltd.com"}},"servers":[{"url":"https://api.coherenceltd.com/v1"}],"tags":[{"name":"Account","description":"Your workspace and its licences."},{"name":"Creator Briefs","description":"Research a product and write a brief creators can film from."},{"name":"Seller Advisor","description":"Answers about TikTok Shop, with sources."},{"name":"ContentIQ","description":"What is selling on TikTok Shop right now, and why."},{"name":"Receipts Manager","description":"Receipts from Gmail, matched to Revolut Business."}],"paths":{"/licences":{"get":{"operationId":"list_licences","summary":"List licences","description":"The tools this workspace is licensed for, which channels each licence covers (web, api, mcp) and how much of this month’s allowance is used. Creator Briefs counts briefs in its own limits, so its usage here may read 0.","tags":["Account"],"security":[{"bearer":["products:read"]}],"x-scope":"products:read","x-products":[],"x-mcp-tool":"list_licences","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","enum":["creator-briefs","seller-advisor","content-iq","receipts"]},"name":{"type":"string"},"channels":{"type":"array","items":{"type":"string","enum":["web","api","mcp"]}},"monthly_allowance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units included each calendar month (UTC)."},"used_this_month":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renews_or_ends_at":{"type":["string","null"]}},"required":["product","name","channels","monthly_allowance","used_this_month","renews_or_ends_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. details lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope, or the workspace lacks a Business licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or allowance reached. See RateLimit-* and Retry-After headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/briefs":{"get":{"operationId":"list_briefs","summary":"List briefs","description":"Creator briefs in this workspace, newest first.","tags":["Creator Briefs"],"security":[{"bearer":["creator-briefs:read"]}],"x-scope":"creator-briefs:read","x-products":["creator-briefs"],"x-mcp-tool":"list_briefs","parameters":[{"name":"status","in":"query","required":false,"description":"Only briefs with this status.","schema":{"description":"Only briefs with this status.","type":"string","enum":["queued","researching","writing","checking","ready","failed"]}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1–100.","schema":{"default":20,"description":"How many items to return, 1–100.","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Pass next_cursor from the previous page to continue.","schema":{"description":"Pass next_cursor from the previous page to continue.","type":"string","maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"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)$"},"status":{"type":"string","enum":["queued","researching","writing","checking","ready","failed"],"description":"queued → researching → writing → checking → ready, or failed. Usually 3–6 minutes."},"product_name":{"type":"string"},"title":{"description":"Set once the brief is written.","type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"finished_at":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"The brief in the Coherence web app."}},"required":["id","status","product_name","title","created_at","updated_at","finished_at","url"],"additionalProperties":false}},"next_cursor":{"description":"Null when there are no more items.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. details lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope, or the workspace lacks a Business licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or allowance reached. See RateLimit-* and Retry-After headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_brief","summary":"Create a brief","description":"Researches a TikTok Shop product, its best videos and competitors, and writes a brief creators can film from (US market, English). Returns at once with status \"queued\"; the brief is usually ready in 3–6 minutes. Uses one brief from the monthly allowance.","tags":["Creator Briefs"],"security":[{"bearer":["creator-briefs:execute"]}],"x-scope":"creator-briefs:execute","x-products":["creator-briefs"],"x-mcp-tool":"create_brief","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Same as idempotency_key in the body.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_name":{"type":"string","minLength":2,"maxLength":180,"description":"The product, or its TikTok Shop product link."},"product_id":{"description":"TikTok Shop product ID, if you have it.","type":"string","pattern":"^\\d{5,40}$"},"audience":{"description":"Who the creators should speak to.","type":"string","maxLength":1500},"objective":{"description":"What the campaign should achieve.","type":"string","maxLength":1500},"approved_facts":{"description":"Claims creators may make: ingredients, results, offers. Only these are stated as fact.","type":"string","maxLength":10000},"campaign_terms":{"description":"Commission, deadlines, deliverables. Appended to the brief as written.","type":"string","maxLength":3000},"creative_direction":{"type":"string","maxLength":3000},"reference_urls":{"description":"Up to 8 public HTTPS links to videos or pages to learn from.","maxItems":8,"type":"array","items":{"type":"string","format":"uri"}},"idempotency_key":{"description":"A UUID you generate. Retrying with the same key returns the original result instead of doing the work twice. Also accepted as the Idempotency-Key header.","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)$"}},"required":["product_name"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"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)$"},"status":{"type":"string","enum":["queued","researching","writing","checking","ready","failed"],"description":"queued → researching → writing → checking → ready, or failed. Usually 3–6 minutes."},"product_name":{"type":"string"},"title":{"description":"Set once the brief is written.","type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"finished_at":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"The brief in the Coherence web app."},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The campaign as submitted."},"markdown":{"description":"The finished brief, ready to share with creators. Null until status is ready.","type":["string","null"]},"document":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The finished brief as structured data: mission, audience, talking points, angles, shots."},"sources":{"type":"array","items":{},"description":"Products, videos and pages the research used."},"warnings":{"type":"array","items":{}},"error_code":{"type":["string","null"]},"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","status","product_name","title","created_at","updated_at","finished_at","url","input","markdown","document","sources","warnings","error_code","revision"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. details lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope, or the workspace lacks a Business licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or allowance reached. See RateLimit-* and Retry-After headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/briefs/{id}":{"get":{"operationId":"get_brief","summary":"Get a brief","description":"One brief with its status. When status is ready it includes the finished brief as Markdown and as structured data. Poll every 15–30 seconds while it is running.","tags":["Creator Briefs"],"security":[{"bearer":["creator-briefs:read"]}],"x-scope":"creator-briefs:read","x-products":["creator-briefs"],"x-mcp-tool":"get_brief","parameters":[{"name":"id","in":"path","required":true,"description":"The brief ID.","schema":{"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)$","description":"The brief ID."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"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)$"},"status":{"type":"string","enum":["queued","researching","writing","checking","ready","failed"],"description":"queued → researching → writing → checking → ready, or failed. Usually 3–6 minutes."},"product_name":{"type":"string"},"title":{"description":"Set once the brief is written.","type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"finished_at":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"The brief in the Coherence web app."},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The campaign as submitted."},"markdown":{"description":"The finished brief, ready to share with creators. Null until status is ready.","type":["string","null"]},"document":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The finished brief as structured data: mission, audience, talking points, angles, shots."},"sources":{"type":"array","items":{},"description":"Products, videos and pages the research used."},"warnings":{"type":"array","items":{}},"error_code":{"type":["string","null"]},"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","status","product_name","title","created_at","updated_at","finished_at","url","input","markdown","document","sources","warnings","error_code","revision"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. details lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope, or the workspace lacks a Business licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or allowance reached. See RateLimit-* and Retry-After headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/content-iq/hooks":{"get":{"operationId":"list_hooks","summary":"List winning hooks","description":"What is selling on TikTok Shop right now: top videos by category with their hooks, angles, why they work and their sales. One entry per video, strongest first. Refreshed daily.","tags":["ContentIQ"],"security":[{"bearer":["content-iq:read"]}],"x-scope":"content-iq:read","x-products":["content-iq","creator-briefs"],"x-mcp-tool":"list_hooks","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["Beauty & skincare","Wellness","Personal care","Home & kitchen","Fashion","Tech & gadgets"]}},{"name":"sort","in":"query","required":false,"description":"score is Coherence’s blend of reach and sales.","schema":{"default":"score","description":"score is Coherence’s blend of reach and sales.","type":"string","enum":["score","views","units_sold","newest"]}},{"name":"q","in":"query","required":false,"description":"Words to find in the hook or angle.","schema":{"description":"Words to find in the hook or angle.","type":"string","maxLength":80}},{"name":"limit","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":80}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["Beauty & skincare","Wellness","Personal care","Home & kitchen","Fashion","Tech & gadgets"]},"video_id":{"type":"string"},"video_url":{"type":["string","null"]},"hook":{"type":"string","description":"The opening line or moment that stops the scroll."},"angle":{"description":"The creative approach the video takes.","type":["string","null"]},"why_it_works":{"type":["string","null"]},"evidence":{"description":"How the performance was measured.","type":["string","null"]},"views":{"type":["number","null"]},"units_sold":{"type":["number","null"]},"gmv_usd":{"type":["number","null"]},"metric_window_days":{"type":["number","null"]},"is_ad":{"type":["boolean","null"]},"observed_at":{"type":["string","null"]}},"required":["id","category","video_id","video_url","hook","angle","why_it_works","evidence","views","units_sold","gmv_usd","metric_window_days","is_ad","observed_at"],"additionalProperties":false}},"refreshed_at":{"type":["string","null"]}},"required":["data","refreshed_at"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. details lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope, or the workspace lacks a Business licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or allowance reached. See RateLimit-* and Retry-After headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key: \"Authorization: Bearer coh_…\". Scopes: products:read, creator-briefs:read, creator-briefs:execute, seller-advisor:read, seller-advisor:execute, content-iq:read, receipts:read, receipts:documents, receipts:write, receipts:send."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","examples":["unauthorized","insufficient_scope","licence_required","rate_limited"]},"message":{"type":"string"},"details":{},"request_id":{"type":"string","description":"Quote this when contacting support."}}}}}}}}