{"openapi":"3.1.0","info":{"title":"Reachio API","version":"1.0.0","description":"Organic social, paid ads, approvals and creatives of a Reachio agency. Authenticate with \"Authorization: Bearer rk_live_…\" (Agency → API keys, or `php artisan reachio:api-key`). A key acts as the member who made it, limited to its abilities (read, write, publish, approve) and optional brand. 120 requests per minute per key. Answers: {data} or {data, meta}; errors: {message, errors?}. Dates ISO-8601 UTC, money in *_micros of the account currency."},"servers":[{"url":"https://reachio.talivio.com/api"}],"security":[{"bearer":[]}],"tags":[{"name":"account"},{"name":"organic"},{"name":"media"},{"name":"inbox"},{"name":"ads"},{"name":"approvals"},{"name":"creatives"},{"name":"search"}],"paths":{"/v1/openapi.json":{"get":{"tags":["account"],"summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/me":{"get":{"tags":["account"],"summary":"The agency, plan, reachable brands and this key","description":"Needs the `read` ability.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Me"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/brands":{"get":{"tags":["account"],"summary":"Brands this key reaches","description":"Needs the `read` ability.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/brands/{brand}":{"get":{"tags":["account"],"summary":"A brand with its channels, ad accounts and tracking assets","description":"Needs the `read` ability.","parameters":[{"name":"brand","in":"path","required":true,"schema":{"type":"string"},"description":"id or slug"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/BrandDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/channels":{"get":{"tags":["organic"],"summary":"One card per channel: followers, views, reach, engagements and posts against the previous period","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"days","in":"query","schema":{"type":"integer","enum":[7,28],"default":7}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelCard"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts":{"get":{"tags":["organic"],"summary":"Posts by bucket (draft → draft; review → in_review; scheduled → approved, scheduled, publishing; published → published, partial, failed); meta.counts per bucket","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"bucket","in":"query","schema":{"type":"string","enum":["draft","review","scheduled","published"]}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"comma list of statuses"},{"name":"q","in":"query","schema":{"type":"string"},"description":"title or variant text"},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"scheduled_at ≥"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"scheduled_at <"},{"name":"tag_prefix","in":"query","schema":{"type":"string"},"description":"any tag starting with it (blog-…)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["scheduled_at","-scheduled_at","published_at","-published_at","updated_at"]}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PostSummary"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["organic"],"summary":"Create a draft (PostEditor)","description":"Needs the `write` ability.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostInput"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}":{"get":{"tags":["organic"],"summary":"Post detail","description":"Needs the `read` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"tags":["organic"],"summary":"Change a post; any change to what goes out voids its approvals (PostWorkflow)","description":"Needs the `write` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"tags":["organic"],"summary":"Delete a post that never went out (no published variant); its approvals go with it","description":"Needs the `write` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"deleted":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}/unapprove":{"post":{"tags":["approvals"],"summary":"Take an approval back: an approved or scheduled post (not being sent) returns to review with fresh pending approvals","description":"Needs the `approve` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}/manual":{"post":{"tags":["organic"],"summary":"Record a variant posted by hand (channel Reachio cannot send to): it becomes published with the link","description":"Needs the `write` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["permalink"],"properties":{"platform":{"type":"string"},"channel_id":{"type":"integer"},"permalink":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/items":{"get":{"tags":["organic"],"summary":"The mirror: posts as they live on the platforms with their last metrics, newest first; alt text known only for what Reachio published. meta.cards (cards=1) per platform","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string"},"description":"comma list"},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"alt_missing","in":"query","schema":{"type":"boolean"}},{"name":"cards","in":"query","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SocialItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/items/{item}":{"get":{"tags":["organic"],"summary":"One mirrored post","description":"Needs the `read` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SocialItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}/submit":{"post":{"tags":["organic"],"summary":"Send for approval (a brand without stages approves at once); 422 lists the problems in errors.post","description":"Needs the `write` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}/approve":{"post":{"tags":["approvals"],"summary":"Approve the open stage this key's member may decide","description":"Needs the `approve` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"},"stage":{"type":"string","enum":["internal","client"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}/reject":{"post":{"tags":["approvals"],"summary":"Ask for changes: the post returns to draft with the reason","description":"Needs the `approve` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"},"stage":{"type":"string","enum":["internal","client"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}/publish":{"post":{"tags":["organic"],"summary":"Publish an approved post now (sets publish_requested_at; the scheduler sends it within a minute). With ?wait=1 PublishService runs in the request","description":"Needs the `publish` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""},{"name":"wait","in":"query","schema":{"type":"integer","enum":[0,1]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"properties":{"confirm":{"type":"boolean","const":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublishResult"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/posts/{post}/cancel":{"post":{"tags":["organic"],"summary":"Cancel a draft, in-review, approved or scheduled post","description":"Needs the `write` ability.","parameters":[{"name":"post","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/media":{"get":{"tags":["media"],"summary":"The brand's media library (signed URLs that expire)","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"type","in":"query","schema":{"type":"string","enum":["image","video"]}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["media"],"summary":"Add a file (multipart `file`) or fetch one (`url`); alt_text is required","description":"Needs the `write` ability.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["alt_text"],"properties":{"brand":{"type":"string"},"file":{"type":"string","format":"binary"},"url":{"type":"string","format":"uri"},"alt_text":{"type":"string"},"ai_generated":{"type":"boolean"}}}},"application/json":{"schema":{"type":"object","required":["alt_text"],"properties":{"brand":{"type":"string"},"file":{"type":"string","format":"binary"},"url":{"type":"string","format":"uri"},"alt_text":{"type":"string"},"ai_generated":{"type":"boolean"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Media"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox":{"get":{"tags":["inbox"],"summary":"Comments, replies, DMs and mentions","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"status","in":"query","schema":{"type":"string","enum":["open","replied","done","dismissed","spam","all"],"default":"open"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string"}},{"name":"unread","in":"query","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/{item}/reply":{"post":{"tags":["inbox"],"summary":"Answer on the platform","description":"Needs the `write` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"by":{"type":"string","description":"display name kept with the reply text"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/{item}/done":{"post":{"tags":["inbox"],"summary":"Mark done","description":"Needs the `write` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/summary":{"get":{"tags":["inbox"],"summary":"One card per platform: open and unread counts, what Reachio can do there, the last read","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxCard"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/{item}":{"get":{"tags":["inbox"],"summary":"One item with the mirrored post it answers","description":"Needs the `read` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/{item}/read":{"post":{"tags":["inbox"],"summary":"Mark read","description":"Needs the `read` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/read-all":{"post":{"tags":["inbox"],"summary":"Mark every unread item (optionally of one platform) read","description":"Needs the `read` ability.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string"},"platform":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"marked":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/{item}/draft":{"post":{"tags":["inbox"],"summary":"Save a reply draft (never sent by itself; empty text clears it)","description":"Needs the `write` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"by":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/organic/inbox/{item}/reopen":{"post":{"tags":["inbox"],"summary":"Back to open","description":"Needs the `write` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/platforms":{"get":{"tags":["ads"],"summary":"One summary per ad network","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/period"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsPlatform"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/platforms/{platform}":{"get":{"tags":["ads"],"summary":"Cards, month, daily series, campaign rows, attention and (Google) the credit threshold","description":"Needs the `read` ability.","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string"},"description":"google, meta, linkedin, microsoft, tiktok, pinterest, x, apple"},{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/period"},{"name":"tag","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPlatformDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/platforms/{platform}/campaigns/{campaign}":{"get":{"tags":["ads"],"summary":"A campaign with its ad groups, keywords, ads, devices and search terms","description":"Needs the `read` ability.","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"campaign","in":"path","required":true,"schema":{"type":"string"},"description":"the platform's campaign id"},{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/period"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CampaignDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/search-terms":{"get":{"tags":["ads"],"summary":"Search terms (Google, Microsoft)","description":"Needs the `read` ability.","parameters":[{"name":"platform","in":"query","schema":{"type":"string","default":"google"}},{"name":"campaign","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/period"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchTerm"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/change-sets":{"get":{"tags":["ads"],"summary":"Change sets","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"status","in":"query","schema":{"type":"string","enum":["open","draft","pending_approval","approved","executing","done","failed","rejected","reverted"]}},{"name":"platform","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangeSet"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["ads"],"summary":"Ask for a change (source api). It waits for approval; with apply=true a reversible lowering by a key with `approve` whose member may execute ad changes is approved and executed at once. Apple Ads creation (create_campaign / create_ad_group / create_keyword + spec) always waits for approval and is created PAUSED","description":"Needs the `write` ability.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeSetInput"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ChangeSet"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/change-sets/{changeSet}/revert":{"post":{"tags":["ads"],"summary":"Undo an executed change (within 7 days; same approval rules)","description":"Needs the `write` ability.","parameters":[{"name":"changeSet","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ChangeSet"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/approvals":{"get":{"tags":["approvals"],"summary":"Approvals of posts, ad change sets and creatives","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected","superseded"],"default":"pending"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["posts","ads","creatives"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Approval"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/approvals/{approval}/decide":{"post":{"tags":["approvals"],"summary":"Approve or reject; the last approval of a change set executes it","description":"Needs the `approve` ability.","parameters":[{"name":"approval","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject"]},"note":{"type":"string","description":"required when rejecting"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Approval"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/creatives":{"get":{"tags":["creatives"],"summary":"Creative projects","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"kind","in":"query","schema":{"type":"string","enum":["banner","social","copy","ad_package","instant","ai_image","upload"]}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CreativeProject"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/creatives/{project}":{"get":{"tags":["creatives"],"summary":"A project with its creatives (signed URLs)","description":"Needs the `read` ability.","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CreativeProjectDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/creatives/upload":{"post":{"tags":["creatives"],"summary":"Add a design made elsewhere (multipart `file` or `url`, alt_text required); a new upload project unless `project` is given","description":"Needs the `write` ability.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["alt_text"],"properties":{"brand":{"type":"string"},"file":{"type":"string","format":"binary"},"url":{"type":"string","format":"uri"},"alt_text":{"type":"string"},"name":{"type":"string"},"project":{"type":"integer"},"ai_generated":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}}}},"application/json":{"schema":{"type":"object","required":["alt_text"],"properties":{"brand":{"type":"string"},"file":{"type":"string","format":"binary"},"url":{"type":"string","format":"uri"},"alt_text":{"type":"string"},"name":{"type":"string"},"project":{"type":"integer"},"ai_generated":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CreativeProjectDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/platforms/{platform}/breakdowns":{"get":{"tags":["ads"],"summary":"Country, placement or hour-of-day split of the period (ad_breakdowns), optionally of one campaign; hour rows in hour order","description":"Needs the `read` ability.","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string"},"description":""},{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/period"},{"name":"dimension","in":"query","schema":{"type":"string","enum":["country","placement","hour"],"default":"country"}},{"name":"campaign","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Breakdown"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/platforms/{platform}/changes":{"get":{"tags":["ads"],"summary":"Account change history (Google change_event: who changed what, through which client), newest first; Google keeps 30 days, the sync stores them","description":"Needs the `read` ability.","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string"},"description":"google"},{"$ref":"#/components/parameters/brand"},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"UTC day; default: 29 days before `to`"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"UTC day; default: today"},{"name":"campaign","in":"query","schema":{"type":"string"},"description":"the platform's campaign id"},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":1000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdChange"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/platforms/{platform}/sync":{"post":{"tags":["ads"],"summary":"Sync the brand's accounts on one network now (mode manual, last `days` 1–7, default 2); synchronous","description":"Needs the `write` ability.","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string"},"description":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string"},"days":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"platform":{"type":"string"},"accounts":{"type":"integer"},"rows":{"type":"integer"},"ok":{"type":"boolean"},"runs":{"type":"array","items":{"type":"object","properties":{"account_id":{"type":"integer"},"rows":{"type":"integer"},"error":{"type":["string","null"]},"finished_at":{"type":["string","null"],"format":"date-time"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/creatives":{"get":{"tags":["ads"],"summary":"The ad creative library of the Talivio hub: one flat list of items over the upload projects (p{project}, c{creative}, s{project}-{n})","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdCreativeItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["ads"],"summary":"New item: an upload project with the hub fields, optional `file` and `poster` (image or video)","description":"Needs the `write` ability.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AdCreativeInput"}},"application/json":{"schema":{"$ref":"#/components/schemas/AdCreativeInput"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdCreativeItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/creatives/{item}":{"get":{"tags":["ads"],"summary":"One item","description":"Needs the `read` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"string"},"description":"p12, c34 or s12-0"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdCreativeItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["ads"],"summary":"Change an item: only the fields sent; `file` / `poster` replace the old ones","description":"Needs the `write` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"string"},"description":""}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AdCreativeInput"}},"application/json":{"schema":{"$ref":"#/components/schemas/AdCreativeInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdCreativeItem"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"tags":["ads"],"summary":"Delete an item (its creatives; the media stay in the library)","description":"Needs the `write` ability.","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"string"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/attention":{"get":{"tags":["ads"],"summary":"Ads attention list, broken or expiring channel connections, failed posts and Search Console items","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AttentionItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/search/report":{"get":{"tags":["search"],"summary":"Search Console report of one brand (optionally one product): totals against the period before, daily and weekly series, brand split, opportunities, queries, pages, movers, cannibalisation, devices, countries, products, sitemaps, index status and alerts. The window keeps the requested length and ends on the latest day Google has data for","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"default: 27 days before `to`"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"default: today (moved back to the latest day with data)"},{"name":"product","in":"query","schema":{"type":"string"},"description":"a brands.settings.products slug: that product's host only"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":5000},"description":"rows of `queries` and `pages` (a CSV export asks for the full list); the other lists keep their sizes"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SearchReport"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/search/properties":{"get":{"tags":["search"],"summary":"Linked Search Console properties with their sync state","description":"Needs the `read` ability.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchProperty"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["search"],"summary":"Link a Search Console property to a brand (the panel's \"Link property\"). The site must be listed for the Google connection; without `connection` the agency's only Search Console-capable Google connection is used (none or several: 422 with the ids). Idempotent: 201 when new, 200 when already linked; the 16-month backfill runs in the background (poll GET for last_status / last_synced_at)","description":"Needs the `write` ability.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_url"],"properties":{"site_url":{"type":"string","maxLength":1024,"description":"`sc-domain:example.com` or a URL prefix such as `https://example.com/`"},"brand":{"type":"string","description":"brand id or slug (optional for a single-brand key)"},"connection":{"type":"integer","description":"Google connection id; optional when the agency has exactly one with Search Console access"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SearchProperty"}}}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SearchProperty"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/search/inspect":{"post":{"tags":["search"],"summary":"Ask Google for the index state of one URL now (spends the property's daily inspection budget)","description":"Needs the `write` ability.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"brand":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SearchInspection"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"rk_live_ followed by 40 characters"}},"parameters":{"brand":{"name":"brand","in":"query","schema":{"type":"string"},"description":"Brand id or slug; not needed when the key is bound to a brand"},"period":{"name":"period","in":"query","schema":{"type":"string","enum":["7d","30d","mtd"],"default":"30d"}},"page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"per_page":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"responses":{"Unauthorized":{"description":"Missing, invalid, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the ability, the member's role does not allow it, or the plan has no API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found (also: another agency's or brand's record)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"Validation failed or the workflow refused (message says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"More than 120 requests a minute for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SearchInspection":{"type":"object","properties":{"id":{"type":"integer"},"product":{"type":["string","null"]},"url":{"type":"string"},"verdict":{"type":["string","null"],"description":"PASS | PARTIAL | FAIL | NEUTRAL | VERDICT_UNSPECIFIED"},"verdict_label":{"type":"string"},"previous_verdict":{"type":["string","null"]},"verdict_changed_at":{"type":["string","null"],"format":"date-time"},"coverage_state":{"type":["string","null"]},"indexing_state":{"type":["string","null"]},"robots_txt_state":{"type":["string","null"]},"page_fetch_state":{"type":["string","null"]},"google_canonical":{"type":["string","null"]},"user_canonical":{"type":["string","null"]},"last_crawl_at":{"type":["string","null"],"format":"date-time"},"checked_at":{"type":["string","null"],"format":"date-time"},"indexed":{"type":"boolean"},"lost_index":{"type":"boolean"},"canonical_mismatch":{"type":"boolean"},"property_id":{"type":"integer","description":"inspect only"},"remaining_today":{"type":"integer","description":"inspect only"}}},"SearchProperty":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"site_url":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["domain","url_prefix"]},"product":{"type":["string","null"]},"reporting":{"type":"boolean","description":"false when a Domain property of the brand already covers it (not counted twice)"},"permission_level":{"type":["string","null"]},"connection_id":{"type":["integer","null"]},"auth":{"type":["string","null"],"enum":["service_account","oauth",null]},"last_status":{"type":["string","null"]},"last_error":{"type":["string","null"]},"synced_until":{"type":["string","null"],"format":"date"},"totals_synced_until":{"type":["string","null"],"format":"date"},"pages_synced_until":{"type":["string","null"],"format":"date"},"last_synced_at":{"type":["string","null"],"format":"date-time"}}},"SearchReport":{"type":"object","properties":{"brand_id":{"type":"integer"},"product":{"type":["string","null"]},"configured":{"type":"boolean"},"latest":{"type":["string","null"],"format":"date"},"synced_at":{"type":["string","null"],"format":"date-time"},"requested":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"window":{"oneOf":[{"type":"null"},{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"integer"}}}]},"current":{"oneOf":[{"type":"null"},{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":["number","null"],"description":"0–1 fraction"},"position":{"type":["number","null"]}}}]},"previous":{"oneOf":[{"type":"null"},{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":["number","null"],"description":"0–1 fraction"},"position":{"type":["number","null"]}}}]},"series":{"type":"array","items":{"allOf":[{"type":"object","properties":{"date":{"type":"string","format":"date"}}},{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":["number","null"],"description":"0–1 fraction"},"position":{"type":["number","null"]}}}]}},"weekly":{"type":"array","items":{"allOf":[{"type":"object","properties":{"week_start":{"type":"string","format":"date"}}},{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":["number","null"],"description":"0–1 fraction"},"position":{"type":["number","null"]}}}]}},"brand_split":{"oneOf":[{"type":"null"},{"type":"object","properties":{"brand":{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"}}},"discovery":{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"}}},"hidden":{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"}}},"total":{"type":"object","properties":{"clicks":{"type":"integer"},"impressions":{"type":"integer"}}}}}]},"opportunities":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"brand":{"type":"boolean"},"page":{"type":["string","null"]},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":"number"},"position":{"type":"number"},"expected_ctr":{"type":"number"},"potential":{"type":"number","description":"estimated extra clicks"},"advice_code":{"type":"string","enum":["second_page","low_ctr_top","low_ctr","near_top","keep"]},"advice":{"type":"string"}}}},"queries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":["number","null"]},"position":{"type":["number","null"]},"brand":{"type":"boolean"}}}},"pages":{"type":"array","items":{"type":"object","properties":{"page":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":["number","null"]},"position":{"type":["number","null"]}}}},"movers":{"type":"object","properties":{"queries":{"type":"object","properties":{"up":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"previous_clicks":{"type":"integer"},"delta":{"type":"integer"},"impressions":{"type":"integer"},"previous_impressions":{"type":"integer"},"position":{"type":["number","null"]},"previous_position":{"type":["number","null"]}}}},"down":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"previous_clicks":{"type":"integer"},"delta":{"type":"integer"},"impressions":{"type":"integer"},"previous_impressions":{"type":"integer"},"position":{"type":["number","null"]},"previous_position":{"type":["number","null"]}}}}}},"pages":{"type":"object","properties":{"up":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"previous_clicks":{"type":"integer"},"delta":{"type":"integer"},"impressions":{"type":"integer"},"previous_impressions":{"type":"integer"},"position":{"type":["number","null"]},"previous_position":{"type":["number","null"]}}}},"down":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"previous_clicks":{"type":"integer"},"delta":{"type":"integer"},"impressions":{"type":"integer"},"previous_impressions":{"type":"integer"},"position":{"type":["number","null"]},"previous_position":{"type":["number","null"]}}}}}}}},"cannibalisation":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"competing":{"type":"boolean"},"pages":{"type":"array","items":{"type":"object","properties":{"page":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"position":{"type":["number","null"]}}}}}}},"devices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"}}}},"countries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"ISO-3 lower case"},"label":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"position":{"type":["number","null"]}}}},"products":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"name":{"type":"string"},"clicks":{"type":"integer"},"previous_clicks":{"type":"integer"},"delta_pct":{"type":["number","null"],"description":"percent (12.5 = +12.5 %), as the hub"},"impressions":{"type":"integer"},"position":{"type":["number","null"]}}}},"sitemaps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"product":{"type":["string","null"]},"path":{"type":"string"},"type":{"type":["string","null"]},"is_sitemaps_index":{"type":"boolean"},"is_pending":{"type":"boolean"},"last_submitted_at":{"type":["string","null"],"format":"date-time"},"last_downloaded_at":{"type":["string","null"],"format":"date-time"},"errors":{"type":"integer"},"warnings":{"type":"integer"},"submitted":{"type":"integer"},"contents":{"type":"array","items":{"type":"object"}},"synced_at":{"type":["string","null"],"format":"date-time"}}}},"products_without_sitemap":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"name":{"type":"string"},"expected":{"type":"string"}}}},"inspection":{"type":"object","properties":{"summary":{"oneOf":[{"type":"null"},{"type":"object","properties":{"total":{"type":"integer"},"indexed":{"type":"integer"},"not_indexed":{"type":"integer"},"errors":{"type":"integer"},"canonical_mismatch":{"type":"integer"},"last_checked_at":{"type":["string","null"],"format":"date-time"}}}]},"problems":{"type":"array","items":{"$ref":"#/components/schemas/SearchInspection"}}}},"alerts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["search_drop","index_lost","sitemap_error","gsc_sync_stale"]},"level":{"type":"string","enum":["danger","warning"]},"ref":{"type":["string","null"]},"count":{"type":["integer","null"]},"at":{"type":["string","null"],"format":"date-time"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["message"]},"PageMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"has_more":{"type":"boolean"},"counts":{"type":"object","description":"posts only: bucket → count","additionalProperties":{"type":"integer"}}},"required":["page","per_page","has_more"]},"Metric":{"type":"object","properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"delta_pct":{"type":["number","null"],"description":"0–1 fraction against the previous period of the same length (0.12 = +12 %); null when the previous value is 0 or missing"}}},"Me":{"type":"object","properties":{"agency":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"timezone":{"type":["string","null"]},"currency":{"type":["string","null"]},"is_internal":{"type":"boolean"}}},"plan":{"type":"object","properties":{"key":{"type":"string"},"brands":{"type":"integer"},"api":{"type":"boolean"}}},"brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"}}}},"key":{"type":"object","properties":{"name":{"type":"string"},"prefix":{"type":"string"},"abilities":{"type":"array","items":{"type":"string","enum":["read","write","publish","approve"]}},"brand_id":{"type":["integer","null"]},"expires_at":{"type":["string","null"],"format":"date-time"}}},"acting_as":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"}}}}},"Brand":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"client_id":{"type":["integer","null"]},"website":{"type":["string","null"]},"timezone":{"type":["string","null"]},"country":{"type":["string","null"]},"locales":{"type":"array","items":{"type":"string"}},"products":{"type":"object","description":"brands.settings.products: slug → {label, prefixes[], website, color}"}}},"BrandDetail":{"allOf":[{"$ref":"#/components/schemas/Brand"},{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"platform":{"type":"string"},"name":{"type":["string","null"]},"handle":{"type":["string","null"]},"status":{"type":"string"},"connection_status":{"type":["string","null"]}}}},"ad_accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"platform":{"type":"string"},"external_id":{"type":"string"},"name":{"type":["string","null"]},"currency":{"type":["string","null"]},"timezone":{"type":["string","null"]},"status":{"type":"string"}}}},"tracking_assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string"},"external_id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":["string","null"]},"install_state":{"type":["string","null"]},"last_fired_at":{"type":["string","null"],"format":"date-time"}}}}}}]},"ChannelCard":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"type":{"type":"string"},"platform":{"type":"string"},"label":{"type":"string"},"handle":{"type":["string","null"]},"connected":{"type":"boolean"},"setup":{"type":"object","properties":{"state":{"type":"string","enum":["ok","never","denied","error","not_connected","unknown"]},"message":{"type":["string","null"]},"connect_url":{"type":["string","null"]},"last_run_at":{"type":["string","null"],"format":"date-time"}}},"followers":{"type":["integer","null"]},"followers_date":{"type":["string","null"],"format":"date"},"follower_change":{"type":["integer","null"]},"views":{"$ref":"#/components/schemas/Metric"},"reach":{"$ref":"#/components/schemas/Metric"},"engagements":{"$ref":"#/components/schemas/Metric"},"posts":{"$ref":"#/components/schemas/Metric"},"engagement_source":{"type":["string","null"],"enum":["account","content",null],"description":"account: the platform's account number; content: summed from mirrored posts"},"publish_mode":{"type":"string","enum":["auto","manual","none"]}}},"PostSummary":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","in_review","approved","scheduled","publishing","published","partial","failed","cancelled"]},"status_label":{"type":"string"},"bucket":{"type":["string","null"],"enum":["draft","review","scheduled","published",null]},"scheduled_at":{"type":["string","null"],"format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"platforms":{"type":"array","items":{"type":"string"}},"excerpt":{"type":["string","null"]},"media_kind":{"type":["string","null"]},"media_count":{"type":"integer"},"thumbnail_url":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"product":{"type":["string","null"],"description":"first tag"},"product_label":{"type":["string","null"],"description":"from brands.settings.products"},"alt_ok":{"type":["boolean","null"],"description":"null when no image needs alt text"},"manual_pending":{"type":"array","items":{"type":"string"},"description":"platforms waiting to be posted by hand (channel not connected)"},"has_error":{"type":"boolean"},"updated_at":{"type":["string","null"],"format":"date-time"},"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"url":{"type":"string"},"alt":{"type":["string","null"]}}}},"alt_problems":{"type":"array","items":{"type":"string"}},"permalinks":{"type":"object","description":"platform → live link"},"approved_at":{"type":["string","null"],"format":"date-time"},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]}}},"Post":{"allOf":[{"$ref":"#/components/schemas/PostSummary"},{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"}}},"approved":{"type":"boolean"},"publish_requested_at":{"type":["string","null"],"format":"date-time"},"texts":{"type":"array","items":{"type":"object","properties":{"channel_id":{"type":"integer"},"channel_type":{"type":"string"},"platform":{"type":"string"},"label":{"type":"string"},"text":{"type":"string"},"length":{"type":"integer"},"limit":{"type":["integer","null"]},"over":{"type":"boolean"},"first_comment":{"type":["string","null"]},"options":{"type":"object"}}}},"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["image","video","document","file"]},"url":{"type":"string"},"alt":{"type":["string","null"]},"cover_url":{"type":["string","null"]}}}},"results":{"type":"array","items":{"type":"object","properties":{"channel_id":{"type":"integer"},"platform":{"type":"string"},"label":{"type":["string","null"]},"state":{"type":"string","enum":["waiting","success","skipped","manual","failed"]},"error":{"type":["string","null"]},"permalink":{"type":["string","null"]},"external_id":{"type":["string","null"]},"at":{"type":["string","null"],"format":"date-time"}}}},"alt_text":{"type":"object","properties":{"required":{"type":"boolean"},"problems":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}}},"approval":{"type":"object","properties":{"stage":{"type":["string","null"]},"stages":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["none","pending","approved","rejected"]},"problems":{"type":"array","items":{"type":"string"}}}},"review_note":{"type":["string","null"]},"last_error":{"type":["string","null"]},"attempts":{"type":"integer"},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"actions":{"type":"object","properties":{"approve":{"type":"boolean"},"reject":{"type":"boolean"},"publish":{"type":"boolean"},"publish_kind":{"type":["string","null"],"enum":["publish","retry",null]},"cancel":{"type":"boolean"},"submit":{"type":"boolean"}}},"created_at":{"type":["string","null"],"format":"date-time"},"cover":{"oneOf":[{"type":"null"},{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"url":{"type":"string"},"alt":{"type":["string","null"]}}}]}}}]},"PostInput":{"type":"object","properties":{"brand":{"type":"string","description":"id or slug"},"title":{"type":"string"},"text":{"type":"string"},"texts":{"type":"object","description":"platform (facebook, x…), channel type or channel id → text","additionalProperties":{"type":"string"}},"channels":{"type":"array","items":{"type":["string","integer"]},"description":"channel ids or platforms/types"},"media":{"type":"array","items":{"oneOf":[{"type":"integer"},{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"alt":{"type":"string"},"ai_generated":{"type":"boolean"}}}]}},"media_kind":{"type":"string","enum":["text","link","image","carousel","video","reel","story","document"]},"first_comment":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"scheduled_at":{"type":"string","format":"date-time"},"link_url":{"type":"string","format":"uri"},"youtube":{"type":"object","properties":{"title":{"type":"string"},"privacy":{"type":"string","enum":["private","unlisted","public"]},"tags":{"type":"array","items":{"type":"string"}}}},"language":{"type":"string","description":"kept in every variant's options (YouTube defaultLanguage)"},"cover":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"alt":{"type":"string"}}}}},"PublishResult":{"type":"object","properties":{"status":{"type":"string"},"queued":{"type":"boolean"},"lines":{"type":"array","items":{"type":"string"}},"post":{"$ref":"#/components/schemas/Post"}}},"Media":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"type":{"type":"string"},"name":{"type":["string","null"]},"mime":{"type":"string"},"size":{"type":"integer"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"duration":{"type":["integer","null"]},"alt":{"type":["string","null"]},"alt_ok":{"type":"boolean"},"ai_generated":{"type":"boolean"},"url":{"type":"string","description":"signed, expires"},"created_at":{"type":["string","null"],"format":"date-time"}}},"InboxItem":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"channel_id":{"type":"integer"},"platform":{"type":["string","null"]},"kind":{"type":"string","enum":["comment","reply","dm","mention","ad_comment","review"]},"status":{"type":"string","enum":["open","replied","done","spam"]},"rating":{"type":["integer","null"],"description":"Google review stars, 1–5"},"author":{"type":"string"},"author_handle":{"type":["string","null"]},"text":{"type":["string","null"]},"permalink":{"type":["string","null"]},"post_permalink":{"type":["string","null"]},"sentiment":{"type":["string","null"]},"assigned_to":{"type":["integer","null"]},"can_reply":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"replied_at":{"type":["string","null"],"format":"date-time"},"author_name":{"type":["string","null"]},"external_id":{"type":"string"},"post_external_id":{"type":["string","null"]},"read_at":{"type":["string","null"],"format":"date-time"},"reply":{"oneOf":[{"type":"null"},{"type":"object","properties":{"source":{"type":"string","enum":["api","platform"]},"text":{"type":["string","null"]},"by":{"type":["string","null"]}}}]},"draft":{"oneOf":[{"type":"null"},{"type":"object","properties":{"text":{"type":"string"},"by":{"type":["string","null"]},"at":{"type":["string","null"],"format":"date-time"}}}]},"reply_awaiting_approval":{"type":"boolean","description":"The agency wants inbox answers approved: the answer is the draft and goes out once approved"}}},"InboxCard":{"type":"object","properties":{"platform":{"type":"string"},"label":{"type":"string"},"connected":{"type":"boolean"},"reason":{"type":["string","null"]},"read":{"type":["boolean","null"]},"reply":{"type":"boolean"},"dm":{"type":["boolean","null"]},"missing":{"type":"array","items":{"type":"string"}},"note":{"type":["string","null"]},"connect_url":{"type":["string","null"]},"needs_setup":{"type":"boolean"},"open":{"type":"integer"},"unread":{"type":"integer"},"run":{"type":"object","properties":{"status":{"type":"string","enum":["ok","never","denied","error"]},"error":{"type":["string","null"]},"finished_at":{"type":["string","null"],"format":"date-time"}}},"last_success_at":{"type":["string","null"],"format":"date-time"}}},"SocialItem":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"channel_id":{"type":"integer"},"platform":{"type":["string","null"]},"kind":{"type":"string"},"external_id":{"type":"string"},"text":{"type":["string","null"]},"permalink":{"type":["string","null"]},"thumb_url":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"metrics":{"type":"object"},"fetched_at":{"type":["string","null"],"format":"date-time"},"media":{"type":"array","items":{"type":"object"}},"alt_status":{"type":"string","enum":["ok","missing","unknown","none"]},"alt_missing":{"type":"integer"},"post":{"oneOf":[{"type":"null"},{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"product":{"type":["string","null"]}}}]}}},"AdsPlatform":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"configured":{"type":"boolean"},"accounts":{"type":"integer"},"currency":{"type":["string","null"]},"conversion_kind":{"type":"string","enum":["conversions","installs"]},"last_synced_at":{"type":["string","null"],"format":"date-time"},"last_sync_error":{"type":["string","null"]},"totals":{"type":"object","properties":{"spend_micros":{"type":"integer"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"number"}}},"attention_count":{"type":"integer"},"pending_approvals":{"type":"integer"}}},"AdRow":{"type":"object","properties":{"id":{"type":"string","description":"the platform's id"},"entity_id":{"type":"integer"},"level":{"type":"string","enum":["campaign","ad_group","ad","keyword","negative_keyword","audience"]},"name":{"type":["string","null"]},"status":{"type":"string","enum":["ENABLED","PAUSED","REMOVED"]},"raw_status":{"type":["string","null"]},"approval_status":{"type":["string","null"]},"review_feedback":{"type":["string","null"]},"daily_budget_micros":{"type":["integer","null"]},"bid_micros":{"type":["integer","null"]},"objective":{"type":["string","null"]},"tag":{"type":["string","null"]},"match_type":{"type":["string","null"]},"campaign_id":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"currency":{"type":["string","null"]},"metrics":{"type":"object","properties":{"spend_micros":{"type":"integer"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"number"},"ctr":{"type":["number","null"],"description":"0–1 fraction"},"avg_cpc_micros":{"type":["integer","null"]},"cost_per_conversion_micros":{"type":["integer","null"]}}},"actions":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"direction":{"type":"string","enum":["down","up"]},"requires_approval":{"type":"boolean"}}}},"extra":{"type":"object","properties":{"serving_status":{"type":["string","null"]},"labels":{"type":"array","items":{"type":"string"}},"quality_score":{"type":["integer","null"]},"first_page_cpc_micros":{"type":["integer","null"]},"top_of_page_cpc_micros":{"type":["integer","null"]},"headlines":{"type":"array","items":{"type":"object"}},"descriptions":{"type":"array","items":{"type":"object"}},"lifetime_budget_micros":{"type":["integer","null"]},"display_status":{"type":["string","null"]},"serving_reasons":{"type":"array","items":{"type":"string"}},"adam_id":{"type":["string","null"]},"countries":{"type":"array","items":{"type":"string"}},"search_match":{"type":["boolean","null"]},"metrics":{"type":"object","description":"period sums: results, reach, all_clicks, engagements, impression shares (0–1)…"}}}}},"AdsPlatformDetail":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"currency":{"type":["string","null"]},"conversion_kind":{"type":"string"},"period":{"type":"object","properties":{"key":{"type":"string"},"from":{"type":"string","format":"date"},"until":{"type":"string","format":"date"}}},"last_synced_at":{"type":["string","null"],"format":"date-time"},"cards":{"type":"object","properties":{"spend":{"$ref":"#/components/schemas/Metric"},"impressions":{"$ref":"#/components/schemas/Metric"},"clicks":{"$ref":"#/components/schemas/Metric"},"conversions":{"$ref":"#/components/schemas/Metric"},"ctr":{"$ref":"#/components/schemas/Metric"},"avg_cpc_micros":{"$ref":"#/components/schemas/Metric"},"cost_per_conversion_micros":{"$ref":"#/components/schemas/Metric"},"results":{"$ref":"#/components/schemas/Metric"},"reach":{"$ref":"#/components/schemas/Metric"},"engagements":{"$ref":"#/components/schemas/Metric"},"all_clicks":{"$ref":"#/components/schemas/Metric"},"new_downloads":{"$ref":"#/components/schemas/Metric"},"redownloads":{"$ref":"#/components/schemas/Metric"}}},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"external_id":{"type":"string"},"name":{"type":["string","null"]},"currency":{"type":["string","null"]},"timezone":{"type":["string","null"]},"status":{"type":"string"},"apps":{"type":"array","items":{"type":"object"}},"monthly_cap_micros":{"type":["integer","null"]},"connection":{"type":"object"},"connect_url":{"type":["string","null"]}}}},"last_sync_error":{"type":["string","null"]},"month":{"type":"object","properties":{"spend_micros":{"type":"integer"},"cap_micros":{"type":"integer"},"daily_budget_micros":{"type":"integer"}}},"series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"spend_micros":{"type":"integer"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"conversions":{"type":"number"}}}},"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/AdRow"}},"attention":{"type":"array","items":{"$ref":"#/components/schemas/AttentionItem"}},"credit":{"oneOf":[{"type":"null"},{"type":"object","properties":{"account_id":{"type":"string"},"currency":{"type":["string","null"]},"since":{"type":"string","format":"date"},"spent_micros":{"type":"integer"},"threshold_micros":{"type":["integer","null"]},"fraction":{"type":["number","null"]},"crossed":{"type":"boolean"},"cap_micros":{"type":["integer","null"]},"paused":{"type":"boolean"},"paused_at":{"type":["string","null"],"format":"date-time"}}}]}}},"CampaignDetail":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/AdRow"},"targets":{"description":"Google campaign criteria; an empty location list = every country, an empty language list = every language. [] on other networks","type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"name":{"type":["string","null"]},"country_code":{"type":["string","null"]}}}},"excluded_locations":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"name":{"type":["string","null"]},"country_code":{"type":["string","null"]}}}},"languages":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"name":{"type":["string","null"]}}}},"devices":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"device":{"type":["string","null"]},"bid_modifier":{"type":["number","null"]},"excluded":{"type":"boolean"}}}},"schedule":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"day_of_week":{"type":["string","null"]},"start":{"type":["string","null"]},"end":{"type":["string","null"]},"bid_modifier":{"type":["number","null"]}}}}}},"ad_groups":{"type":"array","items":{"$ref":"#/components/schemas/AdRow"}},"keywords":{"type":"array","items":{"$ref":"#/components/schemas/AdRow"}},"ads":{"type":"array","items":{"$ref":"#/components/schemas/AdRow"}},"negative_keywords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":["string","null"]},"match_type":{"type":["string","null"]}}}},"devices":{"type":"array","items":{"type":"object"}},"hours":{"type":"array","description":"Google: 24 rows (account time zone); others: [] unless imported","items":{"type":"object","properties":{"hour":{"type":"integer"},"spend_micros":{"type":"integer"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"number"}}}},"countries":{"type":"array","items":{"type":"object"}},"placements":{"type":"array","items":{"type":"object"}},"search_terms":{"type":"array","items":{"$ref":"#/components/schemas/SearchTerm"}}}},"AdChange":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"account_id":{"type":["string","null"]},"resource_name":{"type":"string"},"change_date_time":{"type":["string","null"],"format":"date-time"},"resource_type":{"type":["string","null"]},"operation":{"type":["string","null"]},"changed_fields":{"type":"array","items":{"type":"string"}},"changed_resource":{"type":["string","null"]},"campaign_id":{"type":["string","null"]},"campaign_google_id":{"type":["string","null"]},"campaign_name":{"type":["string","null"]},"user_email":{"type":["string","null"]},"client_type":{"type":["string","null"]}}},"SearchTerm":{"type":"object","properties":{"search_term":{"type":"string"},"campaign_id":{"type":["string","null"]},"campaign_name":{"type":["string","null"]},"ad_group_id":{"type":["string","null"]},"matched_keyword":{"type":["string","null"]},"match_type":{"type":["string","null"]},"metrics":{"type":"object","properties":{"spend_micros":{"type":"integer"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"number"},"ctr":{"type":["number","null"],"description":"0–1 fraction"},"avg_cpc_micros":{"type":["integer","null"]},"cost_per_conversion_micros":{"type":["integer","null"]}}},"actions":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"direction":{"type":"string","enum":["down","up"]},"requires_approval":{"type":"boolean"}}}}}},"ChangeSetInput":{"type":"object","properties":{"brand":{"type":"string"},"platform":{"type":"string"},"entity_id":{"type":"string","description":"the platform's id of the campaign, ad group, ad or keyword; for a creation the PARENT (campaign for create_ad_group, ad group for create_keyword; omitted for create_campaign)"},"account":{"type":"string","description":"create_campaign only: the ad account's platform id (Apple org) when the brand has several"},"level":{"type":"string"},"kind":{"type":"string","enum":["pause","enable","remove","set_daily_budget","set_bid","add_negative_keyword","remove_negative_keyword","create_campaign","create_ad_group","create_keyword"]},"value_micros":{"type":"integer","description":"new budget/bid; for a creation the campaign daily budget, the ad group default bid or the keyword bid when spec does not say"},"keyword_text":{"type":"string"},"match_type":{"type":"string","enum":["PHRASE","EXACT","BROAD"],"description":"Google/Microsoft PHRASE|EXACT, Apple EXACT|BROAD"},"criterion_id":{"type":"string"},"reason":{"type":"string"},"apply":{"type":"boolean","description":"ignored for creations"},"spec":{"type":"object","properties":{"name":{"type":"string","description":"campaign / ad group name, ≤200"},"adam_id":{"type":"string","description":"campaign: App Store app id"},"countries":{"type":"array","items":{"type":"string"},"description":"campaign: 1–60 ISO codes"},"daily_budget_micros":{"type":"integer"},"default_bid_micros":{"type":"integer"},"search_match":{"type":"boolean"},"text":{"type":"string","description":"keyword text, ≤80"},"match_type":{"type":"string","enum":["EXACT","BROAD"]},"bid_micros":{"type":"integer","description":"keyword: own bid (empty = the ad group default)"},"status":{"type":"string","enum":["PAUSED"],"description":"always PAUSED; enabling is a separate `enable` change set"}}}},"required":["platform","kind"]},"ChangeSet":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"platform":{"type":"string"},"kind":{"type":"string"},"kind_label":{"type":"string"},"direction":{"type":"string","enum":["down","up","neutral"]},"status":{"type":"string","enum":["draft","pending_approval","approved","executing","done","failed","rejected","reverted"]},"source":{"type":"string","enum":["user","rule","ai","api"]},"requires_approval":{"type":"boolean","description":"waiting for a person now"},"before":{"type":"object"},"after":{"type":"object"},"summary":{"type":"string"},"reason":{"type":["string","null"]},"error":{"type":["string","null"]},"entity":{"type":"object","properties":{"id":{"type":"string"},"entity_id":{"type":"integer"},"level":{"type":"string"},"name":{"type":["string","null"]},"campaign_id":{"type":["string","null"]},"status":{"type":["string","null"]}}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"stage":{"type":"string"},"status":{"type":"string"},"note":{"type":["string","null"]},"decided_at":{"type":["string","null"],"format":"date-time"}}}},"spec":{"type":["object","null"],"description":"creation: the sealed spec (after.create)"},"created":{"type":["object","null"],"description":"creation, once executed: {id, level, status}; revert removes it"},"revert_of_id":{"type":["integer","null"]},"can_revert":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"executed_at":{"type":["string","null"],"format":"date-time"}}},"Approval":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":["integer","null"]},"kind":{"type":["string","null"],"enum":["posts","ads","creatives",null]},"stage":{"type":"string","enum":["internal","client"]},"status":{"type":"string"},"note":{"type":["string","null"]},"can_decide":{"type":"boolean"},"requested_at":{"type":["string","null"],"format":"date-time"},"requested_by":{"type":["string","null"]},"decided_at":{"type":["string","null"],"format":"date-time"},"decided_by":{"type":["string","null"]},"subject":{"type":"object","properties":{"type":{"type":"string","enum":["post","change_set","creative"]},"id":{"type":"integer"},"title":{"type":["string","null"]},"status":{"type":"string"}}}}},"CreativeProject":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"name":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"error":{"type":["string","null"]},"creatives_count":{"type":"integer"},"thumb_url":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"created_at":{"type":["string","null"],"format":"date-time"}}},"CreativeProjectDetail":{"allOf":[{"$ref":"#/components/schemas/CreativeProject"},{"type":"object","properties":{"inputs":{"type":"object"},"creatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"size":{"type":"string"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"status":{"type":"string"},"media_id":{"type":["integer","null"]},"type":{"type":"string"},"url":{"type":["string","null"]},"alt":{"type":["string","null"]},"alt_ok":{"type":"boolean"},"score":{"type":["integer","null"]},"upload":{"type":"boolean"},"approved":{"type":["boolean","null"]},"rendered_at":{"type":["string","null"],"format":"date-time"}}}}}}]},"Breakdown":{"type":"object","properties":{"value":{"type":"string"},"spend_micros":{"type":"integer"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"number"}}},"AdCreativeItem":{"type":"object","properties":{"id":{"type":"string"},"project_id":{"type":"integer"},"brand_id":{"type":"integer"},"title":{"type":["string","null"]},"slug":{"type":["string","null"]},"product":{"type":["string","null"]},"collection":{"type":["string","null"]},"kind":{"type":["string","null"]},"channel":{"type":["string","null"]},"format":{"type":["string","null"]},"language":{"type":["string","null"]},"status":{"type":["string","null"]},"body":{"type":["string","null"]},"duration_seconds":{"type":["integer","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"source_note":{"type":["string","null"]},"published_to":{"type":"object"},"sort":{"type":"integer"},"file":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdCreativeFile"}]},"poster":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdCreativeFile"}]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"AdCreativeFile":{"type":"object","properties":{"creative_id":{"type":"integer"},"name":{"type":["string","null"]},"mime":{"type":["string","null"]},"type":{"type":"string","enum":["video","image","file"]},"size":{"type":"integer"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"url":{"type":"string","description":"signed, expires"}}},"AdCreativeInput":{"type":"object","properties":{"brand":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"product":{"type":"string"},"collection":{"type":"string"},"kind":{"type":"string"},"channel":{"type":"string"},"format":{"type":"string"},"language":{"type":"string"},"status":{"type":"string"},"body":{"type":"string"},"duration_seconds":{"type":"integer"},"width":{"type":"integer"},"height":{"type":"integer"},"source_note":{"type":"string"},"published_to":{"type":"object"},"sort":{"type":"integer"},"alt_text":{"type":"string"},"file":{"type":"string","format":"binary"},"poster":{"type":"string","format":"binary"},"remove_poster":{"type":"boolean"}}},"AttentionItem":{"type":"object","properties":{"source":{"type":"string","enum":["ads","connection","post","search"]},"type":{"type":"string"},"level":{"type":"string","enum":["danger","warning"]},"count":{"type":["integer","null"],"description":"search only: clicks (search_drop, index_lost) or sitemap errors"},"title":{"type":"string"},"detail":{"type":"string"},"ref":{"type":"string"},"at":{"type":["string","null"],"format":"date-time"},"brand_id":{"type":["integer","null"]},"platform":{"type":["string","null"]},"entity_id":{"type":["integer","null"]},"suggestion":{"oneOf":[{"type":"null"},{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"value_micros":{"type":["integer","null"]}}}]}}}}}}