{"openapi":"3.1.0","info":{"title":"Adeli API","version":"1.0.0","summary":"One REST API to publish, comment, message, and read analytics on Instagram, Facebook, TikTok, YouTube, X, Bluesky, and LinkedIn.","description":"Adeli maintains the developer app on every network, completes each platform's review, and manages OAuth and token refresh, so you hold one API key. Your first 3 connected accounts are free. Guides and examples: https://www.tryadeli.com/docs","contact":{"name":"Adeli","url":"https://www.tryadeli.com","email":"hello@tryadeli.com"},"termsOfService":"https://www.tryadeli.com/terms"},"externalDocs":{"description":"Adeli API documentation","url":"https://www.tryadeli.com/docs"},"servers":[{"url":"https://app.tryadeli.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"API key","description":"Check that a key works and see what it can reach."},{"name":"Profiles","description":"One profile per customer or brand. Every request names its profile."},{"name":"Accounts","description":"Social accounts connected to a profile through OAuth."},{"name":"Posts","description":"Publish and track posts across every connected network."},{"name":"Comments","description":"Read, reply to, and moderate comments."},{"name":"Messages","description":"Direct-message conversations."},{"name":"Webhooks","description":"Signed HTTP callbacks for new comments, inbound direct messages and button taps."},{"name":"Analytics","description":"Account and post insights from each platform."},{"name":"Ads","description":"Meta, TikTok and LinkedIn ad accounts, campaigns (Meta: any objective, with targeting and a new creative), targeting search, insights, and Meta leads, through a profile's Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account, which are separate from its Facebook Pages, TikTok and LinkedIn accounts."},{"name":"Usage","description":"What the workspace has sent this month against the free tier's allowance, and usage that is billed by the platform, such as X API fees."}],"paths":{"/api/v1/me":{"get":{"operationId":"getMe","summary":"Check your API key","description":"Who the key belongs to, which key it is, and the accounts connected to a profile (the default profile unless `profileId` is given). Read-only; the same shape whether or not anything is connected.","tags":["API key"],"parameters":[{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"you":{"type":"object","properties":{"name":{"type":["string","null"]},"organization":{"type":["string","null"]},"profile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"required":["name","organization","profile"]},"apiKey":{"type":"object","properties":{"label":{"type":["string","null"]},"prefix":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["label","prefix","createdAt"]},"accountsConnected":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"username":{"type":["string","null"]}},"required":["accountId","platform","username"]}},"docs":{"type":"string","format":"uri"}},"required":["message","you","apiKey","accountsConnected","docs"]},"examples":{"default":{"summary":"Example","value":{"message":"Your API key works.","you":{"name":"Sam Rivera","organization":"Acme Agency","profile":{"id":"00000000-0000-4000-8000-000000000001","name":"Acme Coffee"}},"apiKey":{"label":"Postman","prefix":"rk_live_Ab3d","createdAt":"2026-11-01T09:00:00.000Z"},"accountsConnected":[{"accountId":"00000000-0000-4000-8000-000000000002","platform":"instagram","username":"acmecoffee"}],"docs":"https://www.tryadeli.com/docs"}}}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/profiles":{"get":{"operationId":"listProfiles","summary":"List profiles","description":"Every profile in the API key's organization, the default first.","tags":["Profiles"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"externalId":{"type":["string","null"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","externalId","metadata","isDefault","createdAt","updatedAt"]}}},"required":["profiles"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createProfile","summary":"Create a profile","description":"Send an `Idempotency-Key` header to make retries safe.","tags":["Profiles"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1},"description":"Optional stable key; reusing it with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"externalId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["name"],"additionalProperties":false},"examples":{"default":{"summary":"A profile for one customer","value":{"name":"Acme Coffee","externalId":"cust_8812","metadata":{"plan":"growth"}}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"externalId":{"type":["string","null"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","externalId","metadata","isDefault","createdAt","updatedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/profiles/{profileId}":{"get":{"operationId":"getProfile","summary":"Get a profile","tags":["Profiles"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"externalId":{"type":["string","null"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","externalId","metadata","isDefault","createdAt","updatedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"put":{"operationId":"updateProfile","summary":"Replace a profile's fields","tags":["Profiles"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"externalId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["name"],"additionalProperties":false},"examples":{"default":{"summary":"Rename a profile","value":{"name":"Acme Coffee Roasters","externalId":"cust_8812","metadata":{"plan":"growth"}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"externalId":{"type":["string","null"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","externalId","metadata","isDefault","createdAt","updatedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"deleteProfile","summary":"Delete a profile and its connected accounts","tags":["Profiles"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/profiles/{profileId}/connect":{"post":{"operationId":"startConnection","summary":"Start connecting a social account","description":"Returns a URL for your customer to authorize the account on the platform.","tags":["Profiles"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"redirectUrl":{"type":"string","format":"uri"},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"handle":{"type":"string","maxLength":253,"pattern":"^(?:did:(?:plc|web):[A-Za-z0-9._:%-]+|@?(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)$"}},"required":["platform"],"additionalProperties":false},"examples":{"default":{"summary":"Connect an Instagram account","value":{"platform":"instagram","redirectUrl":"https://app.example.com/integrations/adeli/callback"}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"status":{"type":"string","enum":["pending_authorization","processing","pending_page_selection","connected","failed","expired"]},"accountId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"}},"required":["code"]},{"type":"null"}]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"authUrl":{"type":"string","format":"uri"}},"required":["id","profileId","platform","status","accountId","expiresAt","completedAt","error"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/profiles/{profileId}/connect/{connectionSessionId}":{"get":{"operationId":"getConnection","summary":"Check a connection's status","tags":["Profiles"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}},{"name":"connectionSessionId","in":"path","required":true,"description":"The id returned when the connection was started.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"status":{"type":"string","enum":["pending_authorization","processing","pending_page_selection","connected","failed","expired"]},"accountId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"}},"required":["code"]},{"type":"null"}]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"authUrl":{"type":"string","format":"uri"}},"required":["id","profileId","platform","status","accountId","expiresAt","completedAt","error"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/accounts":{"get":{"operationId":"listAccounts","summary":"List connected accounts","tags":["Accounts"],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"grantedPermissions":{"type":"array","items":{"type":"string"}},"recommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingRecommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"capabilities":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"capabilityRequirements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"requiredPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"requiredResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}}},"required":["requiredPermissions","missingPermissions","requiredResources","missingResources"]}},"reconnect":{"type":"object","properties":{"action":{"type":"string","const":"restart_oauth"},"method":{"type":"string","const":"POST"},"href":{"type":["string","null"]},"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},"required":["action","method","href","provider"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus","grantedPermissions","recommendedPermissions","missingRecommendedPermissions","capabilities","capabilityRequirements","reconnect"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","accounts","errors"]},"examples":{"default":{"summary":"Example","value":{"status":"complete","accounts":[{"id":"00000000-0000-4000-8000-000000000002","accountId":"00000000-0000-4000-8000-000000000002","profileId":"00000000-0000-4000-8000-000000000001","platform":"instagram","providerId":"17841400000000001","displayName":"Acme Coffee","displayIdentifier":"@acmecoffee","authMethod":"instagram_login","connectionStatus":"connected","grantedPermissions":["instagram_business_basic","instagram_business_content_publish"],"recommendedPermissions":[],"missingRecommendedPermissions":[],"capabilities":{"publish":true},"capabilityRequirements":{},"reconnect":{"action":"restart_oauth","method":"POST","href":"/api/v1/profiles/00000000-0000-4000-8000-000000000001/connect","provider":"instagram"}}],"errors":[]}}}}}},"207":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"grantedPermissions":{"type":"array","items":{"type":"string"}},"recommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingRecommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"capabilities":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"capabilityRequirements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"requiredPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"requiredResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}}},"required":["requiredPermissions","missingPermissions","requiredResources","missingResources"]}},"reconnect":{"type":"object","properties":{"action":{"type":"string","const":"restart_oauth"},"method":{"type":"string","const":"POST"},"href":{"type":["string","null"]},"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},"required":["action","method","href","provider"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus","grantedPermissions","recommendedPermissions","missingRecommendedPermissions","capabilities","capabilityRequirements","reconnect"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","accounts","errors"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/profiles/{profileId}/accounts":{"get":{"operationId":"listProfileAccounts","summary":"List a profile's connected accounts","tags":["Accounts"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"grantedPermissions":{"type":"array","items":{"type":"string"}},"recommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingRecommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"capabilities":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"capabilityRequirements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"requiredPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"requiredResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}}},"required":["requiredPermissions","missingPermissions","requiredResources","missingResources"]}},"reconnect":{"type":"object","properties":{"action":{"type":"string","const":"restart_oauth"},"method":{"type":"string","const":"POST"},"href":{"type":["string","null"]},"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},"required":["action","method","href","provider"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus","grantedPermissions","recommendedPermissions","missingRecommendedPermissions","capabilities","capabilityRequirements","reconnect"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","accounts","errors"]}}}},"207":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"grantedPermissions":{"type":"array","items":{"type":"string"}},"recommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingRecommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"capabilities":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"capabilityRequirements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"requiredPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"requiredResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}}},"required":["requiredPermissions","missingPermissions","requiredResources","missingResources"]}},"reconnect":{"type":"object","properties":{"action":{"type":"string","const":"restart_oauth"},"method":{"type":"string","const":"POST"},"href":{"type":["string","null"]},"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},"required":["action","method","href","provider"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus","grantedPermissions","recommendedPermissions","missingRecommendedPermissions","capabilities","capabilityRequirements","reconnect"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","accounts","errors"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/profiles/{profileId}/accounts/{accountId}":{"get":{"operationId":"getAccount","summary":"Get a connected account","tags":["Accounts"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}},{"name":"accountId","in":"path","required":true,"description":"The connected account's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"xCapabilities":{"type":"object","properties":{"analytics":{"type":"boolean"},"inbox":{"type":"boolean"}},"required":["analytics","inbox"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"updateAccount","summary":"Switch an X account's paid background reads","tags":["Accounts"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}},{"name":"accountId","in":"path","required":true,"description":"The connected account's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"xCapabilities":{"type":"object","properties":{"analytics":{"type":"boolean"},"inbox":{"type":"boolean"}},"additionalProperties":false}},"required":["xCapabilities"]},"examples":{"default":{"summary":"Turn on paid X analytics reads","value":{"xCapabilities":{"analytics":true,"inbox":false}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"xCapabilities":{"type":"object","properties":{"analytics":{"type":"boolean"},"inbox":{"type":"boolean"}},"required":["analytics","inbox"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"disconnectAccount","summary":"Disconnect an account","tags":["Accounts"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}},{"name":"accountId","in":"path","required":true,"description":"The connected account's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"disconnected":{"type":"boolean","const":true},"revocationFailed":{"type":"boolean"}},"required":["id","disconnected"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/profiles/{profileId}/accounts/refresh":{"post":{"operationId":"refreshAccounts","summary":"Refresh every account's access token","tags":["Accounts"],"parameters":[{"name":"profileId","in":"path","required":true,"description":"The profile's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube"]},"refreshed":{"type":"boolean","const":true},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","accountId","profileId","platform","refreshed","expiresAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","accounts","errors"]}}}},"207":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube"]},"refreshed":{"type":"boolean","const":true},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","accountId","profileId","platform","refreshed","expiresAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","accounts","errors"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts":{"get":{"operationId":"listPosts","summary":"List posts","tags":["Posts"],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"caption":{"type":["string","null"]},"media":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]}},"required":["type","url","thumbnailUrl"]}},"permalink":{"type":["string","null"]},"engagement":{"type":"object","properties":{"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"views":{"type":["number","null"]},"reach":{"type":["number","null"]}},"required":["likes","comments"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"status":{"description":"`scheduled` for a post waiting in a scheduled publication; its `id` is the publication target's id. Optional so clients built before it existed still type-check.","type":"string","enum":["published","scheduled"]},"scheduledFor":{"description":"When a scheduled post goes out.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publicationId":{"description":"The scheduled publication this post belongs to.","anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","platform","accountId","profileId","providerId","caption","media","permalink","engagement","publishedAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","posts","errors"]}}}},"207":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"caption":{"type":["string","null"]},"media":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]}},"required":["type","url","thumbnailUrl"]}},"permalink":{"type":["string","null"]},"engagement":{"type":"object","properties":{"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"views":{"type":["number","null"]},"reach":{"type":["number","null"]}},"required":["likes","comments"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"status":{"description":"`scheduled` for a post waiting in a scheduled publication; its `id` is the publication target's id. Optional so clients built before it existed still type-check.","type":"string","enum":["published","scheduled"]},"scheduledFor":{"description":"When a scheduled post goes out.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publicationId":{"description":"The scheduled publication this post belongs to.","anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","platform","accountId","profileId","providerId","caption","media","permalink","engagement","publishedAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","posts","errors"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createPost","summary":"Publish a post","description":"Publish to Instagram, Facebook, TikTok, YouTube, X, Bluesky, or LinkedIn. A LinkedIn post takes at most one of `image`, `images` (2–20 staged images), `video` (one staged MP4), or `document` (one staged PDF with a title), plus optional `mentions`. Instagram requests using only staged upload references are durably accepted with 202 and a status URL; legacy base64 or URL inputs remain synchronous during the compatibility window. Send `multipart/form-data` only for TikTok uploads on this shared endpoint.","tags":["Posts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"caption":{"type":"string","maxLength":2200},"collaborators":{"maxItems":3,"type":"array","items":{"type":"string"}},"isAiGenerated":{"type":"boolean"},"image":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":1},"altText":{"type":"string","maxLength":1000},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username","x","y"],"additionalProperties":false}}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"altText":{"type":"string","maxLength":1000},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username","x","y"],"additionalProperties":false}}},"required":["upload_id"],"additionalProperties":false}]}},"required":["platform","accountId","image"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"caption":{"type":"string","maxLength":2200},"collaborators":{"maxItems":3,"type":"array","items":{"type":"string"}},"isAiGenerated":{"type":"boolean"},"images":{"minItems":2,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":1},"altText":{"type":"string","maxLength":1000},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username","x","y"],"additionalProperties":false}}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"altText":{"type":"string","maxLength":1000},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username","x","y"],"additionalProperties":false}}},"required":["upload_id"],"additionalProperties":false}]}}},"required":["platform","accountId","images"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"caption":{"type":"string","maxLength":2200},"collaborators":{"maxItems":3,"type":"array","items":{"type":"string"}},"isAiGenerated":{"type":"boolean"},"reel":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":89478488},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"],"additionalProperties":false}},"thumbOffsetMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"],"additionalProperties":false}},"thumbOffsetMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"],"additionalProperties":false}},"thumbOffsetMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["upload_id"],"additionalProperties":false}]},"shareToFeed":{"type":"boolean"}},"required":["platform","accountId","reel"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"story":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":1},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username"],"additionalProperties":false}}},"required":["contentType","base64"],"additionalProperties":false},{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":89478488},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username"],"additionalProperties":false}}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username"],"additionalProperties":false}}},"required":["url"],"additionalProperties":false}]},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username"],"additionalProperties":false}}},"required":["upload_id"],"additionalProperties":false}]},"isAiGenerated":{"type":"boolean"}},"required":["platform","accountId","story"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"caption":{"type":"string","maxLength":2200},"collaborators":{"maxItems":3,"type":"array","items":{"type":"string"}},"isAiGenerated":{"type":"boolean"},"carousel":{"minItems":2,"maxItems":10,"type":"array","items":{"anyOf":[{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":1},"altText":{"type":"string","maxLength":1000},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username","x","y"],"additionalProperties":false}}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"altText":{"type":"string","maxLength":1000},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["username","x","y"],"additionalProperties":false}}},"required":["upload_id"],"additionalProperties":false}]},{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":89478488},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"],"additionalProperties":false}},"thumbOffsetMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"],"additionalProperties":false}},"thumbOffsetMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"userTags":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"],"additionalProperties":false}},"thumbOffsetMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["upload_id"],"additionalProperties":false}]}]}}},"required":["platform","accountId","carousel"],"additionalProperties":false}]},{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"message":{"type":"string","maxLength":2200},"image":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":4,"maxLength":5592408}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]}},"required":["platform","accountId","image"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"message":{"type":"string","maxLength":2200},"images":{"minItems":2,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":4,"maxLength":5592408}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]}}},"required":["platform","accountId","images"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"message":{"type":"string","maxLength":2200},"reel":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":89478488}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]}},"required":["platform","accountId","reel"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"message":{"type":"string","maxLength":2200},"video":{"anyOf":[{"type":"object","properties":{"contentType":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":89478488}},"required":["contentType","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]},"title":{"type":"string","maxLength":255}},"required":["platform","accountId","video"],"additionalProperties":false}]},{"type":"object","properties":{"platform":{"type":"string","const":"tiktok"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"post_mode":{"default":"DIRECT_POST","type":"string","enum":["DIRECT_POST","MEDIA_UPLOAD"]},"tiktok_title":{"type":"string","maxLength":2200},"tiktok_description":{"type":"string","maxLength":4000},"privacy_level":{"type":"string","enum":["PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR","SELF_ONLY"]},"disable_comment":{"default":false,"type":"boolean"},"disable_duet":{"default":false,"type":"boolean"},"disable_stitch":{"default":false,"type":"boolean"},"cover_timestamp":{"default":1000,"type":"integer","minimum":0,"maximum":9007199254740991},"photo_cover_index":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"auto_add_music":{"default":false,"type":"boolean"},"is_aigc":{"default":false,"type":"boolean"},"brand_content_toggle":{"default":false,"type":"boolean"},"brand_organic_toggle":{"default":false,"type":"boolean"},"music_usage_confirmed":{"type":"boolean","const":true},"remove_editor_attribution":{"type":"boolean"},"video":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":89478488}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]},"photos":{"minItems":1,"maxItems":35,"type":"array","items":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":4,"maxLength":27962040}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]}},"scheduled_date":{"not":{}},"add_to_queue":{"not":{}},"async_upload":{"not":{}}},"required":["platform","accountId","music_usage_confirmed"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"youtube"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string"},"tags":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"category_id":{"type":"string","pattern":"^\\d+$"},"privacy_status":{"type":"string","enum":["public","unlisted","private"]},"made_for_kids":{"type":"boolean"},"contains_synthetic_media":{"type":"boolean"},"publish_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"notify_subscribers":{"type":"boolean"},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"content_type":{"type":"string","enum":["video/mp4","video/quicktime","video/webm"]},"base64":{"type":"string","minLength":4,"maxLength":89478488}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]},"thumbnail":{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}},"required":["platform","accountId","title","privacy_status","made_for_kids","video"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"x"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"text":{"type":"string","maxLength":25000},"media":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif","video/mp4"]},"base64":{"type":"string","minLength":4,"maxLength":89478488}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]}},"thread":{"maxItems":24,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","maxLength":25000},"media":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif","video/mp4"]},"base64":{"type":"string","minLength":4,"maxLength":89478488}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]}}},"required":["text"],"additionalProperties":false}}},"required":["platform","accountId","text"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"bluesky"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"text":{"type":"string","maxLength":3000},"images":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":4,"maxLength":27962028},"altText":{"type":"string","maxLength":2000}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"altText":{"type":"string","maxLength":2000}},"required":["upload_id"],"additionalProperties":false}]}},"video":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":139810136},"altText":{"type":"string","maxLength":2000}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string","maxLength":2000}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"altText":{"type":"string","maxLength":2000}},"required":["upload_id"],"additionalProperties":false}]},"langs":{"maxItems":3,"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$"}},"thread":{"maxItems":24,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","maxLength":3000},"images":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"base64":{"type":"string","minLength":4,"maxLength":27962028},"altText":{"type":"string","maxLength":2000}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"altText":{"type":"string","maxLength":2000}},"required":["upload_id"],"additionalProperties":false}]}},"video":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","const":"video/mp4"},"base64":{"type":"string","minLength":4,"maxLength":139810136},"altText":{"type":"string","maxLength":2000}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string","maxLength":2000}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"altText":{"type":"string","maxLength":2000}},"required":["upload_id"],"additionalProperties":false}]}},"required":["text"],"additionalProperties":false}}},"required":["platform","accountId","text"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"linkedin"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"commentary":{"type":"string"},"mentions":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"urn":{"type":"string","pattern":"^urn:li:(organization|person):\\d+$"},"name":{"type":"string","minLength":1,"maxLength":200},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["urn","name","offset"],"additionalProperties":false}},"image":{"anyOf":[{"type":"object","properties":{"content_type":{"type":"string","enum":["image/jpeg","image/png","image/gif"]},"base64":{"type":"string","minLength":4,"maxLength":27962028},"title":{"type":"string","maxLength":400}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","maxLength":400}},"required":["upload_id"],"additionalProperties":false}]},"images":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"alt_text":{"type":"string","maxLength":4086}},"required":["upload_id"],"additionalProperties":false}},"video":{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","maxLength":400}},"required":["upload_id"],"additionalProperties":false},"document":{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","minLength":1,"maxLength":400}},"required":["upload_id","title"],"additionalProperties":false}},"required":["platform","accountId","commentary"],"additionalProperties":false}]},"examples":{"instagramImage":{"summary":"Instagram image","value":{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","caption":"Our autumn blend is back. ☕","image":{"upload_id":"instagram/staging/opaque.jpg","altText":"A latte with leaf art"}}},"instagramReel":{"summary":"Instagram Reel","value":{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","caption":"60 seconds of roasting.","reel":{"upload_id":"instagram/staging/opaque.mp4"},"shareToFeed":true}},"facebookImage":{"summary":"Facebook Page photo","value":{"platform":"facebook","accountId":"00000000-0000-4000-8000-000000000002","message":"Our autumn blend is back.","image":{"upload_id":"facebook/staging/opaque.jpg"}}},"tiktokVideo":{"summary":"TikTok video","value":{"platform":"tiktok","accountId":"00000000-0000-4000-8000-000000000002","post_mode":"DIRECT_POST","tiktok_title":"How we roast","privacy_level":"SELF_ONLY","disable_comment":false,"disable_duet":false,"disable_stitch":false,"music_usage_confirmed":true,"video":{"upload_id":"tiktok/staging/opaque.mp4"}}},"youtubeVideo":{"summary":"YouTube video","value":{"platform":"youtube","accountId":"00000000-0000-4000-8000-000000000002","title":"How we roast our autumn blend","privacy_status":"private","made_for_kids":false,"video":{"upload_id":"youtube/staging/opaque.mp4"}}},"xText":{"summary":"X post","value":{"platform":"x","accountId":"00000000-0000-4000-8000-000000000002","text":"Our autumn blend is back."}},"blueskyText":{"summary":"Bluesky post","value":{"platform":"bluesky","accountId":"00000000-0000-4000-8000-000000000002","text":"Our autumn blend is back.","langs":["en"]}},"linkedinImage":{"summary":"LinkedIn image","value":{"platform":"linkedin","accountId":"00000000-0000-4000-8000-000000000002","commentary":"Our autumn blend is back.","image":{"upload_id":"linkedin/staging/opaque.jpg"}}},"linkedinDocument":{"summary":"LinkedIn document","value":{"platform":"linkedin","accountId":"00000000-0000-4000-8000-000000000002","commentary":"Our 2026 sourcing report.","document":{"upload_id":"linkedin/staging/opaque.pdf","title":"2026 sourcing report"}}}}},"multipart/form-data":{"schema":{"type":"object","required":["platform","accountId","music_usage_confirmed"],"properties":{"platform":{"type":"string","description":"`tiktok`."},"accountId":{"type":"string","description":"The connected TikTok account to publish from."},"profileId":{"type":"string"},"video":{"type":"string","format":"binary","description":"The TikTok video file."},"photos[]":{"type":"array","items":{"type":"string","format":"binary"},"description":"TikTok photo-post files."},"post_mode":{"type":"string"},"tiktok_title":{"type":"string"},"tiktok_description":{"type":"string"},"privacy_level":{"type":"string"},"disable_comment":{"type":"string","description":"`true` or `false`."},"disable_duet":{"type":"string","description":"`true` or `false`."},"disable_stitch":{"type":"string","description":"`true` or `false`."},"cover_timestamp":{"type":"string","description":"Non-negative milliseconds."},"photo_cover_index":{"type":"string","description":"Non-negative photo index."},"auto_add_music":{"type":"string","description":"`true` or `false`."},"is_aigc":{"type":"string","description":"`true` or `false`."},"brand_content_toggle":{"type":"string","description":"`true` or `false`."},"brand_organic_toggle":{"type":"string","description":"`true` or `false`."},"music_usage_confirmed":{"type":"string","description":"`true`; required by TikTok."}}},"examples":{"tiktokVideo":{"summary":"TikTok video (multipart)","value":{"platform":"tiktok","accountId":"00000000-0000-4000-8000-000000000002","post_mode":"DIRECT_POST","tiktok_title":"How we roast","privacy_level":"SELF_ONLY","music_usage_confirmed":"true"}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"caption":{"type":["string","null"]},"media":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]}},"required":["type","url","thumbnailUrl"]}},"permalink":{"type":["string","null"]},"engagement":{"type":"object","properties":{"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"views":{"type":["number","null"]},"reach":{"type":["number","null"]}},"required":["likes","comments"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"status":{"description":"`scheduled` for a post waiting in a scheduled publication; its `id` is the publication target's id. Optional so clients built before it existed still type-check.","type":"string","enum":["published","scheduled"]},"scheduledFor":{"description":"When a scheduled post goes out.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publicationId":{"description":"The scheduled publication this post belongs to.","anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"resizedImages":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"image":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["index","image"]}}},"required":["id","platform","accountId","profileId","providerId","caption","media","permalink","engagement","publishedAt"]},{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["published","partial"]},"platform":{"type":"string","enum":["x","bluesky"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"permalink":{"type":"string","format":"uri"},"posts":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","const":"published"},"providerId":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["index","status","providerId","url"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["failed","not_attempted"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["index","status"]}]}},"resizedImages":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"image":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["index","image"]}}},"required":["id","status","platform","accountId","profileId","providerId","permalink","posts"]}]}}}},"202":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing"]},"statusUrl":{"type":"string"}},"required":["jobId","platform","accountId","profileId","status","statusUrl"]},{"type":"object","properties":{"platform":{"type":"string","const":"tiktok"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"publishId":{"type":"string"},"status":{"type":"string","const":"ACCEPTED"},"statusUrl":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"required":["platform","accountId","profileId","publishId","status","statusUrl"]},{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"publishId":{"type":"string"},"status":{"type":"string","const":"ACCEPTED"},"statusUrl":{"type":"string"}},"required":["platform","accountId","profileId","publishId","status","statusUrl"]},{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","const":"youtube"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"publishId":{"type":"string"},"videoId":{"type":"string"},"permalink":{"type":"string","format":"uri"},"status":{"type":"string","const":"ACCEPTED"},"requestedPrivacy":{"type":"string","enum":["public","unlisted","private"]},"appliedPrivacy":{"type":"string","enum":["public","unlisted","private"]},"privacyRestricted":{"type":"boolean"},"publishAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"thumbnail":{"anyOf":[{"type":"string","enum":["set","not_allowed","failed"]},{"type":"null"}]},"statusUrl":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"required":["id","platform","accountId","profileId","publishId","videoId","permalink","status","requestedPrivacy","appliedPrivacy","privacyRestricted","publishAt","thumbnail","statusUrl"]}]},"examples":{"default":{"summary":"Example","value":{"jobId":"00000000-0000-4000-8000-000000000004","platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","profileId":"00000000-0000-4000-8000-000000000001","status":"queued","statusUrl":"/api/v1/posts/instagram/status?jobId=00000000-0000-4000-8000-000000000004&profileId=00000000-0000-4000-8000-000000000001"}}}}}},"207":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["published","partial"]},"platform":{"type":"string","enum":["x","bluesky"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"permalink":{"type":"string","format":"uri"},"posts":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","const":"published"},"providerId":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["index","status","providerId","url"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["failed","not_attempted"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["index","status"]}]}},"resizedImages":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"image":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["index","image"]}}},"required":["id","status","platform","accountId","profileId","providerId","permalink","posts"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Uploaded media is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/media/uploads":{"post":{"operationId":"createMediaUploads","summary":"Prepare direct media uploads","description":"Create short-lived, object-scoped S3 PUT descriptors. Upload each file with the returned headers unchanged, then pass its uploadId as upload_id when publishing. Name one `platform`, or several `platforms` to upload a file once and use it in a publication to all of them; each file must fit every listed platform's limits.","tags":["Posts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"platforms":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]}},"files":{"minItems":1,"maxItems":35,"type":"array","items":{"type":"object","properties":{"clientId":{"type":"string","minLength":1,"maxLength":100},"purpose":{"type":"string","enum":["post_media","youtube_thumbnail"]},"contentType":{"type":"string","minLength":1,"maxLength":100},"size":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"filename":{"type":"string","minLength":1,"maxLength":255}},"required":["clientId","purpose","contentType","size"],"additionalProperties":false}}},"required":["profileId","files"],"additionalProperties":false},"examples":{"default":{"summary":"Stage one image for Instagram","value":{"profileId":"00000000-0000-4000-8000-000000000001","platform":"instagram","files":[{"clientId":"photo","purpose":"post_media","contentType":"image/jpeg","size":482113,"filename":"latte-art.jpg"}]}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"uploads":{"type":"array","items":{"type":"object","properties":{"clientId":{"type":"string"},"uploadId":{"type":"string"},"method":{"type":"string","const":"PUT"},"url":{"type":"string","format":"uri"},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["clientId","uploadId","method","url","headers","expiresAt"],"additionalProperties":false}}},"required":["uploads"],"additionalProperties":false},"examples":{"default":{"summary":"Example","value":{"uploads":[{"clientId":"photo","uploadId":"instagram/staging/opaque.jpg","method":"PUT","url":"https://signed-s3-url.example/instagram/staging/opaque.jpg","headers":{"content-type":"image/jpeg","cache-control":"public, max-age=300","x-amz-server-side-encryption":"AES256"},"expiresAt":"2026-11-06T12:10:00.000Z"}]}}}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/publications":{"post":{"operationId":"createPublication","summary":"Publish one post to several accounts","description":"Shared `content` and `media` go to every target in `platforms`; a target's own `content`, `media`, and `options` (that platform's `createPost` fields) override them. Every target is validated as `createPost` would validate it, then the publication is accepted durably with 202 and a `statusUrl`. Poll `getPublication` until `status` is `published`, `partial`, or `failed`. With `scheduledFor` (one minute to 365 days ahead) the publication is stored with status `scheduled` and answered with 201; Adeli publishes it within about a minute of that time. With `draft: true` it is stored as a `draft` until `publishPublication` or `updatePublication` with a `scheduledFor`. Staged media of a scheduled publication or draft is kept until it is published or canceled; `{ url }` media is fetched when it is published.","tags":["Posts"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1},"description":"Optional stable key; a retry with the same key and body returns the original publication with 200, and a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string","format":"uuid"},"content":{"type":"string","maxLength":25000},"media":{"maxItems":35,"type":"array","items":{"anyOf":[{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false}]}},"platforms":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["image","carousel","video","reel","story"]},"content":{"type":"string","maxLength":25000},"media":{"maxItems":35,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"options":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["platform","accountId"],"additionalProperties":false}},"scheduledFor":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When to publish, as ISO 8601 with a UTC offset, from one minute to 365 days ahead. Adeli publishes within about a minute of this time."},"timeZone":{"type":"string","minLength":1,"maxLength":64,"description":"The IANA time zone the time was chosen in, such as America/New_York. Stored only to show the time back the same way."},"draft":{"description":"Save the publication as a draft. It is published only by publishPublication or by giving it a scheduledFor.","type":"boolean"}},"required":["platforms"],"additionalProperties":false},"examples":{"default":{"summary":"One post to Instagram and LinkedIn","value":{"profileId":"00000000-0000-4000-8000-000000000001","content":"Our autumn blend is back.","media":[{"upload_id":"shared/staging/opaque.jpg"}],"platforms":[{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","kind":"image"},{"platform":"linkedin","accountId":"00000000-0000-4000-8000-000000000007","content":"Our autumn blend is back, roasted in small batches."}]}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"listPublications","summary":"List publications","description":"Publications in the profile, newest first, or soonest first with `status=scheduled`. Filter by `status`, `platform`, or `accountId`; page with `cursor` and `limit`.","tags":["Posts"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"]},"description":"Only publications in this status. Scheduled ones are listed soonest first; others newest first."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"description":"Only publications with a target on this platform."},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only publications with a target on this account."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"},"description":"nextCursor from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Publications per page, 1–100. Defaults to 25."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"publications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}},"nextCursor":{"description":"Pass as cursor for the next page; null on the last page.","type":["string","null"]}},"required":["publications","nextCursor"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/publications/{publicationId}":{"patch":{"operationId":"updatePublication","summary":"Reschedule or edit a scheduled publication or draft","description":"Only while the publication is `scheduled` or a `draft`. `scheduledFor` reschedules it (a draft becomes scheduled). `platforms`, with optional `content` and `media`, replaces the post, validated as `createPublication` would. Answers 409 once the publication has started or was canceled.","tags":["Posts"],"parameters":[{"name":"publicationId","in":"path","required":true,"description":"The publication's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledFor":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When to publish, as ISO 8601 with a UTC offset, from one minute to 365 days ahead. Adeli publishes within about a minute of this time."},"timeZone":{"type":"string","minLength":1,"maxLength":64,"description":"The IANA time zone the time was chosen in, such as America/New_York. Stored only to show the time back the same way."},"content":{"type":"string","maxLength":25000},"media":{"maxItems":35,"type":"array","items":{"anyOf":[{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false}]}},"platforms":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["image","carousel","video","reel","story"]},"content":{"type":"string","maxLength":25000},"media":{"maxItems":35,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"options":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["platform","accountId"],"additionalProperties":false}}},"additionalProperties":false},"examples":{"default":{"summary":"Replace a scheduled post's text","value":{"content":"Our autumn blend is back, from Friday.","platforms":[{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","kind":"image"}],"media":[{"upload_id":"shared/staging/opaque.jpg"}]}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"cancelPublication","summary":"Cancel a scheduled publication or draft","description":"The publication becomes `canceled` and is never published; its kept media is deleted. Answers 409 once it has started.","tags":["Posts"],"parameters":[{"name":"publicationId","in":"path","required":true,"description":"The publication's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"getPublication","summary":"Check a publication's progress","description":"The publication's status, its overall `progress` from 0 to 1, and each target's status, result, and error.","tags":["Posts"],"parameters":[{"name":"publicationId","in":"path","required":true,"description":"The publication's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/publications/{publicationId}/publish":{"post":{"operationId":"publishPublication","summary":"Publish a scheduled publication or draft now","description":"Starts the publication at once, as `createPublication` without `scheduledFor` would. Poll `getPublication` for progress. Answers 409 once it has started or was canceled.","tags":["Posts"],"parameters":[{"name":"publicationId","in":"path","required":true,"description":"The publication's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/publications/{publicationId}/retry":{"post":{"operationId":"retryPublication","summary":"Retry a publication's failed targets","description":"Re-runs only `failed` targets with their original inputs. A target that may already be live (`outcome_unknown`) is never retried. Answers 409 while the publication is running or when nothing failed.","tags":["Posts"],"parameters":[{"name":"publicationId","in":"path","required":true,"description":"The publication's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/youtube":{"post":{"operationId":"uploadYouTubeVideo","summary":"Upload a video file to YouTube","description":"Recommended: send JSON with staged video and optional thumbnail upload references created by `createMediaUploads`. Legacy multipart remains supported for compatibility.","tags":["Posts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"youtube"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string"},"tags":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"category_id":{"type":"string","pattern":"^\\d+$"},"privacy_status":{"type":"string","enum":["public","unlisted","private"]},"made_for_kids":{"type":"boolean"},"contains_synthetic_media":{"type":"boolean"},"publish_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"notify_subscribers":{"type":"boolean"},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"content_type":{"type":"string","enum":["video/mp4","video/quicktime","video/webm"]},"base64":{"type":"string","minLength":4,"maxLength":89478488}},"required":["content_type","base64"],"additionalProperties":false},{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}]},"thumbnail":{"type":"object","properties":{"upload_id":{"type":"string","minLength":1,"maxLength":300}},"required":["upload_id"],"additionalProperties":false}},"required":["platform","accountId","title","privacy_status","made_for_kids","video"],"additionalProperties":false},"examples":{"default":{"summary":"A private video with a thumbnail","value":{"platform":"youtube","accountId":"00000000-0000-4000-8000-000000000002","title":"How we roast our autumn blend","description":"From green beans to the cup.","privacy_status":"private","made_for_kids":false,"video":{"upload_id":"youtube/staging/opaque.mp4"},"thumbnail":{"upload_id":"youtube/staging/opaque.jpg"}}}}},"multipart/form-data":{"schema":{"type":"object","required":["accountId","video","title","privacy_status","made_for_kids"],"properties":{"platform":{"type":"string","description":"`youtube`."},"accountId":{"type":"string"},"profileId":{"type":"string"},"video":{"type":"string","format":"binary","description":"The video file."},"thumbnail":{"type":"string","format":"binary","description":"Optional JPEG or PNG thumbnail."},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"string"},"category_id":{"type":"string"},"privacy_status":{"type":"string","description":"`public`, `unlisted`, or `private`."},"made_for_kids":{"type":"string","description":"`true` or `false`. Required."},"contains_synthetic_media":{"type":"string"},"publish_at":{"type":"string","description":"ISO 8601 time to publish a private video."},"notify_subscribers":{"type":"string"}}}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","const":"youtube"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"publishId":{"type":"string"},"videoId":{"type":"string"},"permalink":{"type":"string","format":"uri"},"status":{"type":"string","const":"ACCEPTED"},"requestedPrivacy":{"type":"string","enum":["public","unlisted","private"]},"appliedPrivacy":{"type":"string","enum":["public","unlisted","private"]},"privacyRestricted":{"type":"boolean"},"publishAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"thumbnail":{"anyOf":[{"type":"string","enum":["set","not_allowed","failed"]},{"type":"null"}]},"statusUrl":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"required":["id","platform","accountId","profileId","publishId","videoId","permalink","status","requestedPrivacy","appliedPrivacy","privacyRestricted","publishAt","thumbnail","statusUrl"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"413":{"description":"Uploaded media is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/x/{postId}":{"delete":{"operationId":"deleteXPost","summary":"Delete an X post","tags":["Posts"],"parameters":[{"name":"postId","in":"path","required":true,"description":"The provider's post id.","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"deleted":{"type":"boolean","const":true},"platform":{"type":"string","const":"x"}},"required":["id","accountId","providerId","deleted","platform"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/bluesky/{postId}":{"delete":{"operationId":"deleteBlueskyPost","summary":"Delete a Bluesky post","tags":["Posts"],"parameters":[{"name":"postId","in":"path","required":true,"description":"The provider's post id.","schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"deleted":{"type":"boolean","const":true},"platform":{"type":"string","const":"bluesky"}},"required":["id","accountId","providerId","deleted","platform"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/instagram/status":{"get":{"operationId":"getInstagramPostStatus","summary":"Check an Instagram post's publishing status","tags":["Posts"],"parameters":[{"name":"jobId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"statusUrl":{"type":"string"},"status":{"type":"string","enum":["queued","processing"]}},"required":["jobId","platform","accountId","profileId","statusUrl","status"]},{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"statusUrl":{"type":"string"},"status":{"type":"string","const":"published"},"post":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"caption":{"type":["string","null"]},"media":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]}},"required":["type","url","thumbnailUrl"]}},"permalink":{"type":["string","null"]},"engagement":{"type":"object","properties":{"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"views":{"type":["number","null"]},"reach":{"type":["number","null"]}},"required":["likes","comments"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"status":{"description":"`scheduled` for a post waiting in a scheduled publication; its `id` is the publication target's id. Optional so clients built before it existed still type-check.","type":"string","enum":["published","scheduled"]},"scheduledFor":{"description":"When a scheduled post goes out.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publicationId":{"description":"The scheduled publication this post belongs to.","anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","platform","accountId","profileId","providerId","caption","media","permalink","engagement","publishedAt"]}},"required":["jobId","platform","accountId","profileId","statusUrl","status","post"]},{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"statusUrl":{"type":"string"},"status":{"type":"string","enum":["failed","outcome_unknown"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["jobId","platform","accountId","profileId","statusUrl","status","error"]}]},"examples":{"default":{"summary":"Example","value":{"jobId":"00000000-0000-4000-8000-000000000004","platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","profileId":"00000000-0000-4000-8000-000000000001","statusUrl":"/api/v1/posts/instagram/status?jobId=00000000-0000-4000-8000-000000000004&profileId=00000000-0000-4000-8000-000000000001","status":"published","post":{"id":"17900000000000003","platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","profileId":"00000000-0000-4000-8000-000000000001","providerId":"17900000000000003","caption":"Our autumn blend is back. ☕","media":[{"type":"IMAGE","url":"https://media.example/instagram/17900000000000003.jpg","thumbnailUrl":null}],"permalink":"https://www.instagram.com/p/EXAMPLE/","engagement":{"likes":0,"comments":0},"publishedAt":"2026-11-06T12:01:30.000Z"}}}}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/instagram/stories":{"get":{"operationId":"listInstagramStories","summary":"List an Instagram account's active stories","description":"Reads the account's live stories from Instagram, newest first: the last 24 hours, with `expiresAt` 24 hours after `timestamp`. `mediaUrl` is null for video with licensed audio. Live video stories and reshared stories are never included. Not cached.","tags":["Posts"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"stories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The story's Instagram media id."},"mediaType":{"description":"IMAGE or VIDEO.","type":["string","null"]},"mediaProductType":{"type":"string","description":"Always STORY."},"mediaUrl":{"description":"The story's image or video. Null for video with licensed audio; use thumbnailUrl or permalink instead. Expires with the story.","type":["string","null"]},"thumbnailUrl":{"description":"A video story's cover image. Null for images.","type":["string","null"]},"permalink":{"description":"The story on Instagram, viewable only while it is live.","type":["string","null"]},"timestamp":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When the story was posted."},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When the story stops being live: 24 hours after timestamp."}},"required":["id","mediaType","mediaProductType","mediaUrl","thumbnailUrl","permalink","timestamp","expiresAt"]},"description":"Active stories, newest first."}},"required":["platform","accountId","profileId","stories"]},"examples":{"default":{"summary":"Example","value":{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","profileId":"00000000-0000-4000-8000-000000000001","stories":[{"id":"17900000000000003","mediaType":"VIDEO","mediaProductType":"STORY","mediaUrl":null,"thumbnailUrl":"https://scontent.cdninstagram.com/v/story-cover.jpg","permalink":"https://instagram.com/stories/acmecoffee/3480000000000000003","timestamp":"2026-11-10T15:20:00.000Z","expiresAt":"2026-11-11T15:20:00.000Z"},{"id":"17900000000000002","mediaType":"IMAGE","mediaProductType":"STORY","mediaUrl":"https://scontent.cdninstagram.com/v/story.jpg","thumbnailUrl":null,"permalink":"https://instagram.com/stories/acmecoffee/3480000000000000002","timestamp":"2026-11-10T09:05:00.000Z","expiresAt":"2026-11-11T09:05:00.000Z"}]}}}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/facebook/status":{"get":{"operationId":"getFacebookPostStatus","summary":"Check a Facebook video's processing status","tags":["Posts"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"publishId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9._~-]+$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"publishId":{"type":"string"},"status":{"type":"string","enum":["PROCESSING","READY","ERROR"]},"phase":{"type":["string","null"]},"permalink":{"type":["string","null"]},"failureReason":{"type":["string","null"]}},"required":["platform","accountId","profileId","publishId","status","phase","permalink","failureReason"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/tiktok/status":{"get":{"operationId":"getTikTokPostStatus","summary":"Check a TikTok post's publishing status","tags":["Posts"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"publishId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9._~-]+$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"tiktok"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"publishId":{"type":"string"},"status":{"type":"string"},"publicPostId":{"type":["string","null"]},"publicPostIds":{"type":"array","items":{"type":"string"}},"failureReason":{"type":["string","null"]},"publiclyAvailable":{"type":["boolean","null"]},"source":{"type":"string","enum":["webhook","provider"]}},"required":["platform","accountId","profileId","publishId","status","publicPostId","publicPostIds","failureReason","publiclyAvailable","source"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/tiktok/creator-info":{"get":{"operationId":"getTikTokCreatorInfo","summary":"Get a TikTok creator's posting options","description":"TikTok requires showing these options (privacy levels, interaction settings) before posting.","tags":["Posts"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"tiktok"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"creator":{"type":"object","properties":{"nickname":{"type":["string","null"]},"privacyLevelOptions":{"type":"array","items":{"type":"string"}},"commentDisabled":{"type":"boolean"},"duetDisabled":{"type":"boolean"},"stitchDisabled":{"type":"boolean"},"maxVideoPostDurationSec":{"type":"number"}},"required":["nickname","privacyLevelOptions","commentDisabled","duetDisabled","stitchDisabled","maxVideoPostDurationSec"]}},"required":["platform","accountId","profileId","creator"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/posts/youtube/status":{"get":{"operationId":"getYouTubeVideoStatus","summary":"Check a YouTube video's processing status","tags":["Posts"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"videoId","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{6,20}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"youtube"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"videoId":{"type":"string"},"status":{"type":"string","enum":["processing","published","failed"]},"uploadStatus":{"type":["string","null"]},"processingStatus":{"type":["string","null"]},"failureReason":{"type":["string","null"]},"privacyStatus":{"anyOf":[{"type":"string","enum":["public","unlisted","private"]},{"type":"null"}]},"publishAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"permalink":{"type":["string","null"]}},"required":["platform","accountId","profileId","videoId","status","uploadStatus","processingStatus","failureReason","privacyStatus","publishAt","permalink"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/comments":{"get":{"operationId":"listComments","summary":"List comments","tags":["Comments"],"parameters":[{"name":"platform","in":"query","required":true,"schema":{"type":"string","enum":["instagram","facebook","tiktok","youtube"]}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"postId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.-]+$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"postId":{"type":["string","null"]},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"caption":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]},"permalink":{"type":["string","null"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"commentsCount":{"type":["number","null"]},"editable":{"type":"boolean"}},"required":["id","caption","thumbnailUrl","permalink","publishedAt","commentsCount"]}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"mediaId":{"type":"string"},"parentId":{"type":["string","null"]},"authorName":{"type":"string"},"authorFullName":{"type":["string","null"]},"authorHandle":{"type":"string"},"avatarUrl":{"type":["string","null"]},"profileUrl":{"type":["string","null"]},"body":{"type":"string"},"likeCount":{"type":"number"},"isCreator":{"type":"boolean"},"isHidden":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"authorId":{"type":["string","null"]},"liked":{"type":"boolean"},"replyCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"deletable":{"type":"boolean"}},"required":["id","mediaId","parentId","authorName","authorFullName","authorHandle","avatarUrl","profileUrl","body","likeCount","isCreator","isHidden","createdAt"]}},"nextCursor":{"type":["string","null"]},"complete":{"type":"boolean"},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["platform","accountId","profileId","postId","posts","comments","nextCursor","complete","syncedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createComment","summary":"Reply to a post or a comment","tags":["Comments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"postId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.-]+$"},"parentId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.-]+$"},"message":{"type":"string","minLength":1,"maxLength":10000}},"required":["platform","accountId","message"],"additionalProperties":false},"examples":{"default":{"summary":"Reply to a comment","value":{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","parentId":"17900000000000001","message":"Thank you! It's back until December."}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"comment":{"type":"object","properties":{"id":{"type":"string"},"mediaId":{"type":"string"},"parentId":{"type":["string","null"]},"authorName":{"type":"string"},"authorFullName":{"type":["string","null"]},"authorHandle":{"type":"string"},"avatarUrl":{"type":["string","null"]},"profileUrl":{"type":["string","null"]},"body":{"type":"string"},"likeCount":{"type":"number"},"isCreator":{"type":"boolean"},"isHidden":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"authorId":{"type":["string","null"]},"liked":{"type":"boolean"},"replyCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"deletable":{"type":"boolean"}},"required":["id","mediaId","parentId","authorName","authorFullName","authorHandle","avatarUrl","profileUrl","body","likeCount","isCreator","isHidden","createdAt"]}},"required":["platform","accountId","profileId","comment"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/comments/{commentId}":{"patch":{"operationId":"updateComment","summary":"Hide, unhide, or moderate a comment","tags":["Comments"],"parameters":[{"name":"commentId","in":"path","required":true,"description":"The provider's comment id.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"postId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.-]+$"},"hidden":{"type":"boolean"},"liked":{"type":"boolean"}},"required":["platform","accountId"],"additionalProperties":false},"examples":{"default":{"summary":"Hide a comment","value":{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","hidden":true}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"comment":{"type":"object","properties":{"id":{"type":"string"},"hidden":{"type":"boolean"},"liked":{"type":"boolean"}},"required":["id"]}},"required":["platform","accountId","profileId","comment"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"deleteComment","summary":"Delete a comment","tags":["Comments"],"parameters":[{"name":"commentId","in":"path","required":true,"description":"The provider's comment id.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.-]+$"}},{"name":"platform","in":"query","required":true,"schema":{"type":"string","enum":["instagram","facebook","tiktok","youtube"]}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"banAuthor","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"204":{"description":"No content"},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/messages":{"get":{"operationId":"listMessages","summary":"List direct-message conversations","description":"Without conversationKey, every message for the profile, account or platform, oldest first. With conversationKey (which requires accountId; 400 invalid_request otherwise), one conversation read from the history Adeli stores: the newest `limit` messages (default 50, at most 100) before `cursor`, oldest first within the page, and `nextCursor` toward older messages (null at the start of the conversation). Each message carries its conversationKey, and its story when it replies to or mentions an Instagram story. With storyId, only the inbound Instagram messages that replied to that story, from every Instagram account in scope; not combinable with conversationKey or another platform, and never served from the response cache.","tags":["Messages"],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"conversationKey","in":"query","required":false,"schema":{"type":"string","pattern":"^(instagram|facebook|whatsapp):[0-9A-Za-z._-]{1,200}$"},"description":"One conversation's messages: a message's conversationKey. Requires accountId. The response then holds the newest `limit` messages before `cursor`, oldest first, and `nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":500},"description":"nextCursor from the previous page, toward older messages. Requires conversationKey."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Messages per page with conversationKey, 1–100. Defaults to 50."},{"name":"storyId","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{1,40}$"},"description":"Only the inbound Instagram messages that replied to this story: a message's story.id. Each reply's sender is the id to message back. Instagram only."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":["string","null"]},"platform":{"type":"string","enum":["instagram","facebook","whatsapp"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string","enum":["text","template","unsupported"]},"recipient":{"type":["string","null"]},"sender":{"type":["string","null"]},"body":{"type":"string"},"status":{"type":"string"},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"conversationKey":{"description":"`<platform>:<counterparty id>` (an IGSID, a PSID, or a WhatsApp wa_id in digits), scoped to accountId: with accountId it identifies one conversation. Pass it to listMessages to read that conversation. Null when the counterparty is unknown; optional so clients built before it existed still type-check.","type":["string","null"]},"story":{"description":"The Instagram story this message replies to or mentions; null for every other message. Optional so clients built before it existed still type-check.","anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["reply","mention"],"description":"`reply` to one of the account's stories, or a `mention` of the account in someone else's story."},"id":{"description":"The story's id. Pass a reply's story id as storyId to listMessages to read every reply to that story.","type":["string","null"]},"url":{"description":"Instagram's link to the story; it stops working when the story expires.","type":["string","null"]}},"required":["type","id","url"]},{"type":"null"}]}},"required":["id","providerId","platform","accountId","profileId","direction","type","recipient","sender","body","status","occurredAt","createdAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}},"nextCursor":{"description":"Present only when conversationKey is given: pass it as cursor for the next, older page; null when there are no older messages.","type":["string","null"]}},"required":["status","messages","errors"]}}}},"207":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":["string","null"]},"platform":{"type":"string","enum":["instagram","facebook","whatsapp"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string","enum":["text","template","unsupported"]},"recipient":{"type":["string","null"]},"sender":{"type":["string","null"]},"body":{"type":"string"},"status":{"type":"string"},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"conversationKey":{"description":"`<platform>:<counterparty id>` (an IGSID, a PSID, or a WhatsApp wa_id in digits), scoped to accountId: with accountId it identifies one conversation. Pass it to listMessages to read that conversation. Null when the counterparty is unknown; optional so clients built before it existed still type-check.","type":["string","null"]},"story":{"description":"The Instagram story this message replies to or mentions; null for every other message. Optional so clients built before it existed still type-check.","anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["reply","mention"],"description":"`reply` to one of the account's stories, or a `mention` of the account in someone else's story."},"id":{"description":"The story's id. Pass a reply's story id as storyId to listMessages to read every reply to that story.","type":["string","null"]},"url":{"description":"Instagram's link to the story; it stops working when the story expires.","type":["string","null"]}},"required":["type","id","url"]},{"type":"null"}]}},"required":["id","providerId","platform","accountId","profileId","direction","type","recipient","sender","body","status","occurredAt","createdAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}},"nextCursor":{"description":"Present only when conversationKey is given: pass it as cursor for the next, older page; null when there are no older messages.","type":["string","null"]}},"required":["status","messages","errors"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"sendMessage","summary":"Send a direct message","description":"Instagram and Facebook send text. WhatsApp sends an approved `template`, or free `text` (up to 4,096 characters) inside the 24-hour window after the customer's last message, never both. A reply outside a platform's 24-hour window is 409 window_closed.","tags":["Messages"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"recipient":{"type":"string","minLength":1,"maxLength":200},"text":{"type":"string","minLength":1,"maxLength":1000}},"required":["platform","accountId","recipient","text"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"recipient":{"type":"string","minLength":1,"maxLength":200},"text":{"type":"string","minLength":1,"maxLength":1000}},"required":["platform","accountId","recipient","text"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"whatsapp"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"recipient":{"type":"string","pattern":"^\\+?[1-9]\\d{7,14}$"},"template":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-z0-9_]+$"},"language":{"type":"string","pattern":"^[a-z]{2,3}(_[A-Z]{2})?$"},"bodyParameters":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":1024}}},"required":["name","language"],"additionalProperties":false}},"required":["platform","accountId","recipient","template"],"additionalProperties":false},{"type":"object","properties":{"platform":{"type":"string","const":"whatsapp"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"recipient":{"type":"string","pattern":"^\\+?[1-9]\\d{7,14}$"},"text":{"type":"string","minLength":1,"maxLength":4096,"description":"Free text, sent only inside the 24-hour window after the customer's last message; 409 window_closed otherwise. Send a template outside it."}},"required":["platform","accountId","recipient","text"],"additionalProperties":false}]},"examples":{"default":{"summary":"Instagram direct message","value":{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","recipient":"1790000000000002","text":"Thanks for reaching out! Your order ships today."}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":["string","null"]},"platform":{"type":"string","enum":["instagram","facebook","whatsapp"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string","enum":["text","template","unsupported"]},"recipient":{"type":["string","null"]},"sender":{"type":["string","null"]},"body":{"type":"string"},"status":{"type":"string"},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"conversationKey":{"description":"`<platform>:<counterparty id>` (an IGSID, a PSID, or a WhatsApp wa_id in digits), scoped to accountId: with accountId it identifies one conversation. Pass it to listMessages to read that conversation. Null when the counterparty is unknown; optional so clients built before it existed still type-check.","type":["string","null"]},"story":{"description":"The Instagram story this message replies to or mentions; null for every other message. Optional so clients built before it existed still type-check.","anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["reply","mention"],"description":"`reply` to one of the account's stories, or a `mention` of the account in someone else's story."},"id":{"description":"The story's id. Pass a reply's story id as storyId to listMessages to read every reply to that story.","type":["string","null"]},"url":{"description":"Instagram's link to the story; it stops working when the story expires.","type":["string","null"]}},"required":["type","id","url"]},{"type":"null"}]}},"required":["id","providerId","platform","accountId","profileId","direction","type","recipient","sender","body","status","occurredAt","createdAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/messages/instagram":{"post":{"operationId":"sendInstagramMessage","summary":"Send an Instagram message or private reply","description":"A DM to an IGSID, or a private reply to a comment's author (Instagram Login only, one per comment), with up to three postback or URL buttons.","tags":["Messages"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"recipient":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200}},"required":["id"],"additionalProperties":false},{"type":"object","properties":{"commentId":{"type":"string","pattern":"^\\d{1,40}$"}},"required":["commentId"],"additionalProperties":false}]},"text":{"type":"string","minLength":1,"maxLength":1000},"buttons":{"minItems":1,"maxItems":3,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"postback"},"title":{"type":"string","minLength":1,"maxLength":20},"payload":{"type":"string","minLength":1,"maxLength":1000}},"required":["type","title","payload"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"title":{"type":"string","minLength":1,"maxLength":20},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["type","title","url"],"additionalProperties":false}]}}},"required":["accountId","recipient","text"],"additionalProperties":false},"examples":{"default":{"summary":"Private reply with a button","value":{"accountId":"00000000-0000-4000-8000-000000000002","recipient":{"commentId":"17900000000000001"},"text":"Here's your discount code.","buttons":[{"type":"url","title":"Shop now","url":"https://shop.example.com/autumn"}]}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":"string"},"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"direction":{"type":"string","const":"outbound"},"type":{"type":"string","enum":["text","buttons"]},"recipient":{"type":["string","null"]},"sender":{"type":"string"},"body":{"type":"string"},"status":{"type":"string","const":"sent"},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","providerId","platform","accountId","profileId","direction","type","recipient","sender","body","status","occurredAt","createdAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/messages/instagram/users/{igsid}":{"get":{"operationId":"getInstagramUser","summary":"Get an Instagram user who messaged the account","description":"Reads someone who has messaged the Instagram account, live from Instagram: their username and name, and whether they follow the account (`isFollowing`). Instagram shares this only after the person has sent the account a message or tapped one of its buttons; before that it is 409 user_consent_required. An id Instagram does not recognise is 404 user_not_found. Not cached.","tags":["Messages"],"parameters":[{"name":"igsid","in":"path","required":true,"description":"The person's Instagram-scoped user id (IGSID): `message.created` `from.id` or `message.postback` `senderId`.","schema":{"type":"string","pattern":"^\\d{1,40}$"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"user":{"type":"object","properties":{"id":{"type":"string","description":"The Instagram-scoped user id (IGSID)."},"username":{"type":["string","null"]},"name":{"type":["string","null"]},"followerCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isFollowing":{"description":"Whether this person follows the connected account. Null when Instagram did not say.","type":["boolean","null"]},"isFollowedByAccount":{"description":"Whether the connected account follows this person. Null when Instagram did not say.","type":["boolean","null"]}},"required":["id","username","name","followerCount","isFollowing","isFollowedByAccount"]}},"required":["platform","accountId","profileId","user"]},"examples":{"default":{"summary":"Example","value":{"platform":"instagram","accountId":"00000000-0000-4000-8000-000000000002","profileId":"00000000-0000-4000-8000-000000000001","user":{"id":"1790000000000002","username":"maya.makes","name":"Maya","followerCount":812,"isFollowing":true,"isFollowedByAccount":false}}}}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","description":"Lists the profile's webhooks. `platform` is the platform a webhook receives events from, or null for every supported platform. `status` says whether delivery is enabled, not whether the receiver is reachable.","tags":["Webhooks"],"parameters":[{"name":"profileId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["comment.created","message.postback","message.created"]}},"platform":{"description":"The one platform this webhook receives events from, or null for every supported platform. Always present in responses; optional so clients built before it existed still type-check.","anyOf":[{"type":"string","enum":["instagram","tiktok","facebook","whatsapp"]},{"type":"null"}]},"status":{"type":"string","enum":["active","disabled"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","url","events","status","createdAt"]}}},"required":["webhooks"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createWebhook","summary":"Create a webhook","description":"Registers a URL for comment.created, message.postback and message.created events on one profile. Pass `platform` (`instagram`, `tiktok`, `facebook` or `whatsapp`) to receive one platform's events only; omit it to receive every supported platform. Each platform sends only some events: `comment.created` comes from Instagram and TikTok, `message.postback` from Instagram, and `message.created` (inbound direct messages) from Instagram, Facebook and WhatsApp. A platform with an event it does not send is 422 unsupported_for_platform. The signing secret is returned only in this response.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string","format":"uuid"},"url":{"type":"string","minLength":1,"maxLength":2048},"events":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["comment.created","message.postback","message.created"]}},"platform":{"description":"Receive events from this platform only. Omit to receive every supported platform. `message.postback` requires `instagram` or no platform; `comment.created` requires `instagram`, `tiktok` or no platform; `message.created` requires `instagram`, `facebook`, `whatsapp` or no platform.","type":"string","enum":["instagram","tiktok","facebook","whatsapp"]}},"required":["profileId","url","events"],"additionalProperties":false},"examples":{"default":{"summary":"Comments and button taps on one profile","value":{"profileId":"00000000-0000-4000-8000-000000000001","url":"https://app.example.com/webhooks/adeli","events":["comment.created","message.postback"],"platform":"instagram"}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["comment.created","message.postback","message.created"]}},"platform":{"description":"The one platform this webhook receives events from, or null for every supported platform. Always present in responses; optional so clients built before it existed still type-check.","anyOf":[{"type":"string","enum":["instagram","tiktok","facebook","whatsapp"]},{"type":"null"}]},"status":{"type":"string","enum":["active","disabled"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","url","events","status","createdAt"]},"secret":{"type":"string"}},"required":["webhook","secret"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/webhooks/{webhookId}":{"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","tags":["Webhooks"],"parameters":[{"name":"webhookId","in":"path","required":true,"description":"The webhook's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/webhooks/{webhookId}/test":{"post":{"operationId":"testWebhook","summary":"Send a test event","description":"Sends one signed sample event (`test: true`) to the webhook now and returns the receiver's status code. One attempt, no retries; at most one test per webhook every few seconds. Defaults to a TikTok `comment.created`. A type the platform does not send is 422 unsupported_for_platform.","tags":["Webhooks"],"parameters":[{"name":"webhookId","in":"path","required":true,"description":"The webhook's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"default":"comment.created","type":"string","enum":["comment.created","message.postback","message.created"]},"platform":{"default":"tiktok","type":"string","enum":["instagram","tiktok","facebook","whatsapp"]}},"additionalProperties":false},"examples":{"default":{"summary":"A sample TikTok comment","value":{"type":"comment.created","platform":"tiktok"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"eventId":{"type":"string"},"delivered":{"type":"boolean"},"statusCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"error":{"type":["string","null"]}},"required":["eventId","delivered","statusCode","error"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/instagram/account-insights":{"get":{"operationId":"getInstagramAccountInsights","summary":"Instagram account insights","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"The connected account. It names its profile, so `profileId` can be left out."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile, when no `accountId` is given."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"instagram"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"insights":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"period":{"type":"string"},"total_value":{"type":"object","properties":{"value":{"type":"number"}}},"values":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number"},"end_time":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}}}}}},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","insights","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/facebook/page-metrics":{"get":{"operationId":"getFacebookPageMetrics","summary":"Facebook Page metrics","description":"Pass profileId or accountId; accountId selects a specific Facebook connection.","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The connected account. It names its profile, so `profileId` can be left out."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile, when no `accountId` is given."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"facebook"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"page":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"username":{"type":["string","null"]},"category":{"type":["string","null"]},"link":{"type":["string","null"]}},"required":["id","name","username","category","link"]},"metrics":{"type":"object","properties":{"followers":{"type":["number","null"]},"fans":{"type":["number","null"]},"recentPosts":{"type":"integer","minimum":0,"maximum":9007199254740991},"recentPostLikes":{"type":"integer","minimum":0,"maximum":9007199254740991},"recentPostComments":{"type":"integer","minimum":0,"maximum":9007199254740991},"recentPostShares":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["followers","fans","recentPosts","recentPostLikes","recentPostComments","recentPostShares"]},"insights":{"anyOf":[{"type":"object","properties":{"periodDays":{"type":"number"},"views":{"type":["number","null"]},"engagements":{"type":["number","null"]},"pageViews":{"type":["number","null"]},"followers":{"type":["number","null"]},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"value":{"type":"number"}},"required":["date","value"]}}},"required":["periodDays","views","engagements","pageViews","followers","daily"]},{"type":"null"}]},"insightsUnavailable":{"anyOf":[{"type":"string","enum":["permission_missing","analyze_task_missing","provider_error"]},{"type":"null"}]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","page","metrics","insights","insightsUnavailable","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/tiktok/account-analytics":{"get":{"operationId":"getTikTokAccountAnalytics","summary":"TikTok account analytics","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"The connected account. It names its profile, so `profileId` can be left out."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile, when no `accountId` is given."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"tiktok"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"profile":{"type":"object","properties":{"openId":{"type":"string"},"username":{"type":["string","null"]},"displayName":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"profileDeepLink":{"type":["string","null"]},"bioDescription":{"type":["string","null"]},"isVerified":{"type":["boolean","null"]},"isBusinessAccount":{"type":["boolean","null"]}},"required":["openId","username","displayName","avatarUrl","profileDeepLink","bioDescription","isVerified","isBusinessAccount"]},"analytics":{"type":"object","properties":{"followers":{"type":["number","null"]},"following":{"type":["number","null"]},"likes":{"type":["number","null"]},"videos":{"type":["number","null"]}},"required":["followers","following","likes","videos"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","profile","analytics","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/tiktok/account-insights":{"get":{"operationId":"getTikTokAccountInsights","summary":"TikTok account insights (TikTok API for Business)","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"tiktok"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"isBusinessAccount":{"type":["boolean","null"]},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"videoViews":{"type":["number","null"]},"uniqueVideoViews":{"type":["number","null"]},"profileViews":{"type":["number","null"]},"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"followers":{"type":["number","null"]},"newFollowers":{"type":["number","null"]},"lostFollowers":{"type":["number","null"]},"engagedAudience":{"type":["number","null"]},"bioLinkClicks":{"type":["number","null"]},"emailClicks":{"type":["number","null"]},"phoneNumberClicks":{"type":["number","null"]},"addressClicks":{"type":["number","null"]},"appDownloadClicks":{"type":["number","null"]},"leadSubmissions":{"type":["number","null"]},"activity":{"type":"array","items":{"type":"object","properties":{"hour":{"type":"string"},"count":{"type":"number"}},"required":["hour","count"]}}},"required":["date","videoViews","uniqueVideoViews","profileViews","likes","comments","shares","followers","newFollowers","lostFollowers","engagedAudience","bioLinkClicks","emailClicks","phoneNumberClicks","addressClicks","appDownloadClicks","leadSubmissions","activity"]}},"audience":{"type":"object","properties":{"ages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}},"genders":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}},"countries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}},"cities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}}},"required":["ages","genders","countries","cities"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","isBusinessAccount","startDate","endDate","daily","audience","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/tiktok/video-insights":{"get":{"operationId":"getTikTokVideoInsights","summary":"TikTok video insights","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"videoIds","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"tiktok"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"mediaType":{"type":"string","enum":["VIDEO","PHOTO"]},"isAd":{"type":"boolean"},"caption":{"type":["string","null"]},"coverImageUrl":{"type":["string","null"]},"shareUrl":{"type":["string","null"]},"embedUrl":{"type":["string","null"]},"durationSeconds":{"type":["number","null"]},"likeCount":{"type":["number","null"]},"commentCount":{"type":["number","null"]},"shareCount":{"type":["number","null"]},"favoriteCount":{"type":["number","null"]},"viewCount":{"type":["number","null"]},"reach":{"type":["number","null"]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"insights":{"type":"object","properties":{"totalTimeWatchedSeconds":{"type":["number","null"]},"averageTimeWatchedSeconds":{"type":["number","null"]},"fullVideoWatchedRate":{"type":["number","null"]},"newFollowers":{"type":["number","null"]},"profileViews":{"type":["number","null"]},"retention":{"type":"array","items":{"type":"object","properties":{"second":{"type":"string"},"percentage":{"type":"number"}},"required":["second","percentage"]}},"impressionSources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}},"audienceGenders":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}},"audienceCountries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}},"audienceCities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}},"audienceTypes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["name","percentage"]}}},"required":["totalTimeWatchedSeconds","averageTimeWatchedSeconds","fullVideoWatchedRate","newFollowers","profileViews","retention","impressionSources","audienceGenders","audienceCountries","audienceCities","audienceTypes"]}},"required":["id","mediaType","isAd","caption","coverImageUrl","shareUrl","embedUrl","durationSeconds","likeCount","commentCount","shareCount","favoriteCount","viewCount","reach","createdAt"]}},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","videos","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/youtube/channel-insights":{"get":{"operationId":"getYouTubeChannelInsights","summary":"YouTube channel insights","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"youtube"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"channel":{"type":"object","properties":{"channelId":{"type":"string"},"title":{"type":"string"},"handle":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"subscribers":{"type":["number","null"]},"views":{"type":["number","null"]},"videos":{"type":["number","null"]}},"required":["channelId","title","handle","avatarUrl","subscribers","views","videos"]},"insights":{"type":"object","properties":{"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"views":{"type":["number","null"]},"minutesWatched":{"type":["number","null"]},"averageViewDurationSeconds":{"type":["number","null"]},"subscribersGained":{"type":["number","null"]},"subscribersLost":{"type":["number","null"]},"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]}},"required":["date","views","minutesWatched","averageViewDurationSeconds","subscribersGained","subscribersLost","likes","comments","shares"]}},"topVideos":{"type":"array","items":{"type":"object","properties":{"videoId":{"type":"string"},"views":{"type":["number","null"]},"minutesWatched":{"type":["number","null"]},"averageViewDurationSeconds":{"type":["number","null"]},"likes":{"type":["number","null"]},"comments":{"type":["number","null"]}},"required":["videoId","views","minutesWatched","averageViewDurationSeconds","likes","comments"]}},"audience":{"type":"object","properties":{"ageGender":{"type":"array","items":{"type":"object","properties":{"ageGroup":{"type":"string"},"gender":{"type":"string"},"percentage":{"type":["number","null"]}},"required":["ageGroup","gender","percentage"]}},"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"views":{"type":["number","null"]}},"required":["country","views"]}}},"required":["ageGender","countries"]}},"required":["startDate","endDate","daily","topVideos","audience"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","channel","insights","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/youtube/video-insights":{"get":{"operationId":"getYouTubeVideoInsights","summary":"YouTube video insights","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"videoIds","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"youtube"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"insights":{"type":"object","properties":{"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"videos":{"type":"array","items":{"type":"object","properties":{"videoId":{"type":"string"},"views":{"type":["number","null"]},"minutesWatched":{"type":["number","null"]},"averageViewDurationSeconds":{"type":["number","null"]},"averageViewPercentage":{"type":["number","null"]},"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"subscribersGained":{"type":["number","null"]}},"required":["videoId","views","minutesWatched","averageViewDurationSeconds","averageViewPercentage","likes","comments","shares","subscribersGained"]}}},"required":["startDate","endDate","videos"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","insights","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/linkedin/account-insights":{"get":{"operationId":"getLinkedInAccountInsights","summary":"LinkedIn account insights","description":"Followers and a daily series of impressions, reactions, comments, shares and follower gain for a LinkedIn Page or personal profile; clicks and Page views are reported for Pages only. Served from a snapshot refreshed at most every six hours; `stale` is true when LinkedIn rate-limited the refresh.","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"linkedin"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"targetType":{"type":"string","enum":["organization","member"]},"followers":{"type":["number","null"]},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"impressions":{"type":["number","null"]},"clicks":{"type":["number","null"]},"reactions":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"followerGain":{"type":["number","null"]},"pageViews":{"type":["number","null"]}},"required":["date","impressions","clicks","reactions","comments","shares","followerGain","pageViews"]}},"unavailable":{"type":"array","items":{"type":"string"}},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"stale":{"type":"boolean"}},"required":["platform","accountId","profileId","targetType","followers","startDate","endDate","daily","unavailable","fetchedAt","stale"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/analytics/linkedin/post-insights":{"get":{"operationId":"getLinkedInPostInsights","summary":"LinkedIn post insights","description":"Lifetime counters for up to five LinkedIn posts, or the account's recent posts when postUrns is omitted. A personal profile's posts must have been published through Adeli.","tags":["Analytics"],"parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"postUrns","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"linkedin"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"targetType":{"type":"string","enum":["organization","member"]},"posts":{"type":"array","items":{"type":"object","properties":{"postUrn":{"type":"string"},"permalink":{"type":"string","format":"uri"},"title":{"type":["string","null"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"hasImage":{"type":"boolean"},"impressions":{"type":["number","null"]},"clicks":{"type":["number","null"]},"reactions":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]}},"required":["postUrn","permalink","title","publishedAt","hasImage","impressions","clicks","reactions","comments","shares"]}},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","targetType","posts","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The platform is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/businesses":{"get":{"operationId":"listAdBusinesses","summary":"List Meta businesses","description":"Meta only; a TikTok Ads or LinkedIn Ads account returns 400 unsupported_for_platform.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"businesses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"required":["platform","accountId","profileId","businesses"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/accounts":{"get":{"operationId":"listAdAccounts","summary":"List ad accounts","description":"Meta ad accounts (`act_<digits>`), TikTok advertisers (`<digits>`) or LinkedIn ad accounts (`<digits>`, with the member's `role`, `readOnly` and the `organizationUrn` whose posts they sponsor), depending on the account's network.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Optional boolean string; `true` bypasses the cached list, while `false` (or omission) uses the cache."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"currency":{"type":["string","null"]},"timezoneName":{"type":["string","null"]},"accountStatus":{"type":["number","string","null"]},"minDailyBudget":{"type":["number","null"]},"businessId":{"type":["string","null"]},"businessName":{"type":["string","null"]},"role":{"type":["string","null"]},"readOnly":{"type":"boolean"},"organizationUrn":{"type":["string","null"]},"test":{"type":"boolean"}},"required":["id","accountId","name","currency","timezoneName","accountStatus","minDailyBudget","businessId","businessName"]}},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","adAccounts","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createAdAccount","summary":"Create an ad account","description":"Meta only.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1},"description":"Required stable key; a replay returns 200 and an in-progress or failed creation returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessId":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","minLength":1,"maxLength":100},"currency":{"default":"USD","type":"string","enum":["USD","CAD","MXN","BRL","GBP","EUR","AUD","NZD","INR","SGD","AED","JPY"]},"timezone":{"type":"string","enum":["America/Los_Angeles","America/Denver","Pacific/Honolulu","America/Anchorage","America/Phoenix","America/Chicago","America/New_York","America/Toronto","America/Vancouver","America/Mexico_City","America/Sao_Paulo","Europe/London","Europe/Dublin","Europe/Paris","Europe/Berlin","Europe/Madrid","Europe/Amsterdam","Asia/Dubai","Asia/Kolkata","Asia/Singapore","Asia/Tokyo","Australia/Sydney","Pacific/Auckland","UTC"]}},"required":["businessId","name","timezone"],"additionalProperties":false},"examples":{"default":{"summary":"A Meta ad account","value":{"businessId":"1234567890","name":"Acme Coffee Ads","currency":"USD","timezone":"America/New_York"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"adAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"currency":{"type":["string","null"]},"timezoneName":{"type":["string","null"]},"accountStatus":{"type":["number","string","null"]},"minDailyBudget":{"type":["number","null"]},"businessId":{"type":["string","null"]},"businessName":{"type":["string","null"]},"role":{"type":["string","null"]},"readOnly":{"type":"boolean"},"organizationUrn":{"type":["string","null"]},"test":{"type":"boolean"}},"required":["id","accountId","name","currency","timezoneName","accountStatus","minDailyBudget","businessId","businessName"]},{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}]},"replayed":{"type":"boolean"}},"required":["adAccount","replayed"]}}}},"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"adAccount":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"currency":{"type":["string","null"]},"timezoneName":{"type":["string","null"]},"accountStatus":{"type":["number","string","null"]},"minDailyBudget":{"type":["number","null"]},"businessId":{"type":["string","null"]},"businessName":{"type":["string","null"]},"role":{"type":["string","null"]},"readOnly":{"type":"boolean"},"organizationUrn":{"type":["string","null"]},"test":{"type":"boolean"}},"required":["id","accountId","name","currency","timezoneName","accountStatus","minDailyBudget","businessId","businessName"]},{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}]},"replayed":{"type":"boolean"}},"required":["adAccount","replayed"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/accounts/{adAccountId}":{"get":{"operationId":"getAdAccount","summary":"Get an ad account","description":"Meta only.","tags":["Ads"],"parameters":[{"name":"adAccountId","in":"path","required":true,"description":"Meta ad account id, `act_` followed by digits.","schema":{"type":"string","pattern":"^act_\\d+$"}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccount":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"currency":{"type":["string","null"]},"timezoneName":{"type":["string","null"]},"accountStatus":{"type":["number","string","null"]},"minDailyBudget":{"type":["number","null"]},"businessId":{"type":["string","null"]},"businessName":{"type":["string","null"]},"role":{"type":["string","null"]},"readOnly":{"type":"boolean"},"organizationUrn":{"type":["string","null"]},"test":{"type":"boolean"}},"required":["id","accountId","name","currency","timezoneName","accountStatus","minDailyBudget","businessId","businessName"]},"details":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":["string","null"]},"accountStatus":{"type":["number","null"]},"disableReason":{"type":["number","null"]},"spendCap":{"type":["number","null"]},"amountSpent":{"type":["number","null"]},"hasPaymentMethod":{"type":["boolean","null"]}},"required":["id","currency","accountStatus","disableReason","spendCap","amountSpent","hasPaymentMethod"]}},"required":["platform","accountId","profileId","adAccount","details"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"updateAdAccount","summary":"Update an ad account","description":"Meta only.","tags":["Ads"],"parameters":[{"name":"adAccountId","in":"path","required":true,"description":"Meta ad account id, `act_` followed by digits.","schema":{"type":"string","pattern":"^act_\\d+$"}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"spendCap":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":10000000},{"type":"null"}]}},"additionalProperties":false},"examples":{"default":{"summary":"Set a spend cap","value":{"name":"Acme Coffee Ads","spendCap":500}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccount":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"currency":{"type":["string","null"]},"timezoneName":{"type":["string","null"]},"accountStatus":{"type":["number","string","null"]},"minDailyBudget":{"type":["number","null"]},"businessId":{"type":["string","null"]},"businessName":{"type":["string","null"]},"role":{"type":["string","null"]},"readOnly":{"type":"boolean"},"organizationUrn":{"type":["string","null"]},"test":{"type":"boolean"}},"required":["id","accountId","name","currency","timezoneName","accountStatus","minDailyBudget","businessId","businessName"]},"details":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":["string","null"]},"accountStatus":{"type":["number","null"]},"disableReason":{"type":["number","null"]},"spendCap":{"type":["number","null"]},"amountSpent":{"type":["number","null"]},"hasPaymentMethod":{"type":["boolean","null"]}},"required":["id","currency","accountStatus","disableReason","spendCap","amountSpent","hasPaymentMethod"]}},"required":["platform","accountId","profileId","adAccount","details"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/tree":{"get":{"operationId":"getAdTree","summary":"Campaigns, ad sets (TikTok ad groups, LinkedIn campaigns), and ads for an ad account","description":"For LinkedIn, `campaigns` are campaign groups, `adSets` are campaigns, and `ads` are creatives.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^(act_)?\\d+$"}},{"name":"since","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccount":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"currency":{"type":["string","null"]},"timezoneName":{"type":["string","null"]},"accountStatus":{"type":["number","string","null"]},"minDailyBudget":{"type":["number","null"]},"businessId":{"type":["string","null"]},"businessName":{"type":["string","null"]},"role":{"type":["string","null"]},"readOnly":{"type":"boolean"},"organizationUrn":{"type":["string","null"]},"test":{"type":"boolean"}},"required":["id","accountId","name","currency","timezoneName","accountStatus","minDailyBudget","businessId","businessName"]},"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"effectiveStatus":{"type":["string","null"]},"metrics":{"type":"object","properties":{"spend":{"type":"number"},"impressions":{"type":"number"},"reach":{"type":"number"},"clicks":{"type":"number"},"ctr":{"type":["number","null"]},"cpc":{"type":["number","null"]},"cpm":{"type":["number","null"]},"conversions":{"type":["number","null"]},"videoViews":{"type":["number","null"]}},"required":["spend","impressions","reach","clicks","ctr","cpc","cpm","conversions"]},"objective":{"type":["string","null"]},"adSets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"effectiveStatus":{"type":["string","null"]},"metrics":{"type":"object","properties":{"spend":{"type":"number"},"impressions":{"type":"number"},"reach":{"type":"number"},"clicks":{"type":"number"},"ctr":{"type":["number","null"]},"cpc":{"type":["number","null"]},"cpm":{"type":["number","null"]},"conversions":{"type":["number","null"]},"videoViews":{"type":["number","null"]}},"required":["spend","impressions","reach","clicks","ctr","cpc","cpm","conversions"]},"budget":{"type":["number","null"]},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"effectiveStatus":{"type":["string","null"]},"metrics":{"type":"object","properties":{"spend":{"type":"number"},"impressions":{"type":"number"},"reach":{"type":"number"},"clicks":{"type":"number"},"ctr":{"type":["number","null"]},"cpc":{"type":["number","null"]},"cpm":{"type":["number","null"]},"conversions":{"type":["number","null"]},"videoViews":{"type":["number","null"]}},"required":["spend","impressions","reach","clicks","ctr","cpc","cpm","conversions"]},"postUrn":{"type":["string","null"]}},"required":["id","name","status","effectiveStatus","metrics"]}}},"required":["id","name","status","effectiveStatus","metrics","ads"]}}},"required":["id","name","status","effectiveStatus","metrics","objective","adSets"]}},"range":{"type":"object","properties":{"since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["since","until"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","adAccount","campaigns","range","fetchedAt"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/insights":{"get":{"operationId":"getAdInsights","summary":"Ad performance insights","description":"A daily series (`points`), or with `breakdown` totals split by one dimension (`rows`). Meta points and rows also carry reach, CTR, CPC, CPM, every action and its value (`actions`, `actionValues`, `costPerAction`), `conversionValue`, `roas`, and `results`/`costPerResult` for conversions or the `resultActionType` asked for.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^(act_)?\\d+$"}},{"name":"objectId","in":"query","required":false,"schema":{"type":"string"},"description":"A campaign, ad set (ad group), or ad id."},{"name":"level","in":"query","required":false,"schema":{"type":"string","enum":["campaign","ad_group","ad"]},"description":"TikTok and LinkedIn: the level of `objectId`. Defaults to campaign (a LinkedIn campaign group)."},{"name":"breakdown","in":"query","required":false,"schema":{"anyOf":[{"type":"string","enum":["age","gender","country","region","publisher_platform","platform_position","device_platform"]},{"type":"string","enum":["age","gender","country_code","platform"]},{"type":"string","enum":["job_function","seniority","industry","company_size","country_code"]}]},"description":"Meta (age, gender, country, region, publisher_platform, platform_position, device_platform), TikTok (age, gender, country_code, platform) or LinkedIn (job_function, seniority, industry, company_size, country_code): return a breakdown (`rows`) instead of the daily series (`points`). Meta platform_position rows are labelled `platform:position`. LinkedIn rows carry a `label` and the response `delayed: true`."},{"name":"attributionWindows","in":"query","required":false,"schema":{"type":"string"},"description":"Meta: comma-separated attribution windows, from 1d_click, 7d_click, 28d_click, 1d_view, 1d_ev. The ad account's default when omitted."},{"name":"resultActionType","in":"query","required":false,"schema":{"type":"string"},"description":"Meta: the action type counted as a result for `results` and `costPerResult`, such as link_click or offsite_conversion.fb_pixel_purchase. Conversions when omitted."},{"name":"since","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"until","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"objectId":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"spend":{"type":"number"},"impressions":{"type":"number"},"clicks":{"type":"number"},"conversions":{"type":["number","null"]},"reach":{"type":"number"},"ctr":{"type":["number","null"]},"cpc":{"type":["number","null"]},"cpm":{"type":["number","null"]},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"}},"required":["type","value"]}},"actionValues":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"}},"required":["type","value"]}},"costPerAction":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"}},"required":["type","value"]}},"conversionValue":{"type":["number","null"]},"roas":{"type":["number","null"]},"results":{"type":["number","null"]},"costPerResult":{"type":["number","null"]}},"required":["date","spend","impressions","clicks","conversions","reach","ctr","cpc","cpm","actions","actionValues","costPerAction","conversionValue","roas","results","costPerResult"]}},"attributionWindows":{"type":"array","items":{"type":"string","enum":["1d_click","7d_click","28d_click","1d_view","1d_ev"]}},"range":{"type":"object","properties":{"since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["since","until"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","adAccountId","objectId","points","range","fetchedAt"]},{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"objectId":{"type":"string"},"breakdown":{"type":"string","enum":["age","gender","country","region","publisher_platform","platform_position","device_platform"]},"rows":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"spend":{"type":"number"},"impressions":{"type":"number"},"clicks":{"type":"number"},"conversions":{"type":["number","null"]},"reach":{"type":"number"},"ctr":{"type":["number","null"]},"cpc":{"type":["number","null"]},"cpm":{"type":["number","null"]},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"}},"required":["type","value"]}},"actionValues":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"}},"required":["type","value"]}},"costPerAction":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"}},"required":["type","value"]}},"conversionValue":{"type":["number","null"]},"roas":{"type":["number","null"]},"results":{"type":["number","null"]},"costPerResult":{"type":["number","null"]}},"required":["value","spend","impressions","clicks","conversions","reach","ctr","cpc","cpm","actions","actionValues","costPerAction","conversionValue","roas","results","costPerResult"]}},"attributionWindows":{"type":"array","items":{"type":"string","enum":["1d_click","7d_click","28d_click","1d_view","1d_ev"]}},"range":{"type":"object","properties":{"since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["since","until"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","adAccountId","objectId","breakdown","rows","range","fetchedAt"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"objectId":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"spend":{"type":"number"},"impressions":{"type":"number"},"clicks":{"type":"number"},"conversions":{"type":["number","null"]},"videoViews":{"type":["number","null"]}},"required":["date","spend","impressions","clicks","conversions"]}},"range":{"type":"object","properties":{"since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["since","until"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","adAccountId","objectId","points","range","fetchedAt"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"objectId":{"type":"string"},"breakdown":{"type":"string","enum":["age","gender","country_code","platform"]},"rows":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"spend":{"type":"number"},"impressions":{"type":"number"},"clicks":{"type":"number"},"reach":{"type":"number"}},"required":["value","spend","impressions","clicks","reach"]}},"range":{"type":"object","properties":{"since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["since","until"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","adAccountId","objectId","breakdown","rows","range","fetchedAt"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"objectId":{"type":"string"},"breakdown":{"type":"string","enum":["job_function","seniority","industry","company_size","country_code"]},"rows":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"spend":{"type":"number"},"impressions":{"type":"number"},"clicks":{"type":"number"},"reach":{"type":"number"}},"required":["value","label","spend","impressions","clicks","reach"]}},"delayed":{"type":"boolean","const":true},"range":{"type":"object","properties":{"since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["since","until"]},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","adAccountId","objectId","breakdown","rows","delayed","range","fetchedAt"]}]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/leads":{"get":{"operationId":"listAdLeads","summary":"List lead forms or leads from a lead form","description":"Meta only.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"formId","in":"query","required":false,"schema":{"type":"string"},"description":"Omit to list forms; pass a form id to list its leads."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"forms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"leadsCount":{"type":["number","null"]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","name","status","leadsCount","createdAt"]}},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","forms","fetchedAt"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"leads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["name","values"]}},"campaignName":{"type":["string","null"]},"adSetName":{"type":["string","null"]},"adName":{"type":["string","null"]}},"required":["id","createdAt","fields","campaignName","adSetName","adName"]}},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["platform","accountId","profileId","leads","fetchedAt"]}]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/campaigns":{"post":{"operationId":"createCampaign","summary":"Create a paused campaign","description":"Meta: a body with `objective` builds a full campaign — objective, daily or lifetime budget, schedule, bid strategy, targeting and a new image, video or carousel creative, or a boosted Page or Instagram post — optionally inside an existing campaign or ad set; `validateOnly: true` checks it with Meta, creates nothing and answers 200 with the steps checked. A body without `objective` boosts a Page post. TikTok creates a campaign, ad group and video ad; LinkedIn sponsors a post by the ad account's Page as a campaign group, campaign and creative, all drafts. Everything is created paused or as a draft: nothing spends until setAdStatus activates it.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1},"description":"Required stable key for campaign creation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^act_\\d+$"},"objective":{"type":"string","enum":["traffic","engagement","awareness","video_views","lead_generation","conversions","app_promotion"]},"campaignName":{"type":"string","minLength":1,"maxLength":200},"adName":{"type":"string","minLength":1,"maxLength":200},"campaignId":{"type":"string","pattern":"^\\d+$"},"adSetId":{"type":"string","pattern":"^\\d+$"},"budget":{"type":"object","properties":{"type":{"type":"string","enum":["daily","lifetime"]},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1000000}},"required":["type","amount"],"additionalProperties":false},"budgetLevel":{"default":"ad_set","type":"string","enum":["ad_set","campaign"]},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"bid":{"type":"object","properties":{"strategy":{"type":"string","enum":["lowest_cost","bid_cap","cost_cap","min_roas"]},"amount":{"type":"number","exclusiveMinimum":0,"maximum":10000},"roasFloor":{"type":"number","exclusiveMinimum":0,"maximum":1000}},"required":["strategy"],"additionalProperties":false},"targeting":{"type":"object","properties":{"ageMin":{"type":"integer","minimum":13,"maximum":65},"ageMax":{"type":"integer","minimum":13,"maximum":65},"gender":{"default":"all","type":"string","enum":["all","male","female"]},"locations":{"type":"object","properties":{"countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"regions":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}},"cities":{"maxItems":250,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100},"radius":{"type":"integer","minimum":1,"maximum":80},"distanceUnit":{"type":"string","enum":["mile","kilometer"]}},"required":["key"],"additionalProperties":false}},"zips":{"maxItems":2500,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}}},"additionalProperties":false},"excludedLocations":{"type":"object","properties":{"countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"regions":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}},"cities":{"maxItems":250,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100},"radius":{"type":"integer","minimum":1,"maximum":80},"distanceUnit":{"type":"string","enum":["mile","kilometer"]}},"required":["key"],"additionalProperties":false}},"zips":{"maxItems":2500,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}}},"additionalProperties":false},"interests":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200}},"required":["id"],"additionalProperties":false}},"behaviors":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200}},"required":["id"],"additionalProperties":false}},"demographics":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200},"type":{"type":"string","enum":["life_events","family_statuses","industries","income","education_statuses","relationship_statuses","work_positions","work_employers","education_schools","education_majors","user_adclusters"]}},"required":["id","type"],"additionalProperties":false}},"languages":{"maxItems":50,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"customAudiences":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"excludedCustomAudiences":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"placements":{"default":"automatic","anyOf":[{"type":"string","const":"automatic"},{"type":"object","properties":{"publisherPlatforms":{"minItems":1,"type":"array","items":{"type":"string","enum":["facebook","instagram","audience_network","messenger","threads"]}},"facebookPositions":{"type":"array","items":{"type":"string","enum":["feed","right_hand_column","marketplace","video_feeds","story","search","instream_video","facebook_reels","facebook_reels_overlay","profile_feed","notification"]}},"instagramPositions":{"type":"array","items":{"type":"string","enum":["stream","story","explore","explore_home","reels","profile_feed","ig_search","profile_reels"]}},"audienceNetworkPositions":{"type":"array","items":{"type":"string","enum":["classic","rewarded_video"]}},"messengerPositions":{"type":"array","items":{"type":"string","enum":["messenger_home","sponsored_messages","story"]}},"devicePlatforms":{"type":"array","items":{"type":"string","enum":["mobile","desktop"]}}},"required":["publisherPlatforms"],"additionalProperties":false}]},"advantageAudience":{"default":false,"type":"boolean"}},"required":["locations"],"additionalProperties":false},"creative":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"page_post"},"pagePostId":{"type":"string","pattern":"^\\d+$"}},"required":["type","pagePostId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"instagram_post"},"instagramMediaId":{"type":"string","pattern":"^\\d+$"}},"required":["type","instagramMediaId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"image":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["url"],"additionalProperties":false}]},"headline":{"type":"string","minLength":1,"maxLength":255},"body":{"type":"string","minLength":1,"maxLength":2200},"description":{"type":"string","minLength":1,"maxLength":255},"callToAction":{"type":"string","enum":["LEARN_MORE","SHOP_NOW","SIGN_UP","BOOK_NOW","CONTACT_US","DOWNLOAD","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","APPLY_NOW","ORDER_NOW","BUY_NOW","INSTALL_MOBILE_APP","USE_APP","DONATE_NOW","GET_DIRECTIONS","SEE_MENU","PLAY_GAME","LISTEN_NOW","NO_BUTTON"]},"linkUrl":{"type":"string","maxLength":2000,"format":"uri"}},"required":["type","image"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"video"},"video":{"anyOf":[{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["url"],"additionalProperties":false}]},{"type":"object","properties":{"videoId":{"type":"string","pattern":"^\\d+$"}},"required":["videoId"],"additionalProperties":false}]},"thumbnail":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["url"],"additionalProperties":false}]},"headline":{"type":"string","minLength":1,"maxLength":255},"body":{"type":"string","minLength":1,"maxLength":2200},"description":{"type":"string","minLength":1,"maxLength":255},"callToAction":{"type":"string","enum":["LEARN_MORE","SHOP_NOW","SIGN_UP","BOOK_NOW","CONTACT_US","DOWNLOAD","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","APPLY_NOW","ORDER_NOW","BUY_NOW","INSTALL_MOBILE_APP","USE_APP","DONATE_NOW","GET_DIRECTIONS","SEE_MENU","PLAY_GAME","LISTEN_NOW","NO_BUTTON"]},"linkUrl":{"type":"string","maxLength":2000,"format":"uri"}},"required":["type","video"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"carousel"},"body":{"type":"string","minLength":1,"maxLength":2200},"linkUrl":{"type":"string","maxLength":2000,"format":"uri"},"callToAction":{"type":"string","enum":["LEARN_MORE","SHOP_NOW","SIGN_UP","BOOK_NOW","CONTACT_US","DOWNLOAD","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","APPLY_NOW","ORDER_NOW","BUY_NOW","INSTALL_MOBILE_APP","USE_APP","DONATE_NOW","GET_DIRECTIONS","SEE_MENU","PLAY_GAME","LISTEN_NOW","NO_BUTTON"]},"cards":{"minItems":2,"maxItems":10,"type":"array","items":{"type":"object","properties":{"image":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["url"],"additionalProperties":false}]},"headline":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","minLength":1,"maxLength":255},"linkUrl":{"type":"string","maxLength":2000,"format":"uri"},"callToAction":{"type":"string","enum":["LEARN_MORE","SHOP_NOW","SIGN_UP","BOOK_NOW","CONTACT_US","DOWNLOAD","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","APPLY_NOW","ORDER_NOW","BUY_NOW","INSTALL_MOBILE_APP","USE_APP","DONATE_NOW","GET_DIRECTIONS","SEE_MENU","PLAY_GAME","LISTEN_NOW","NO_BUTTON"]}},"required":["image"],"additionalProperties":false}}},"required":["type","cards"],"additionalProperties":false}]},"instagramAccountId":{"type":"string","pattern":"^\\d+$"},"pixelId":{"type":"string","pattern":"^\\d+$"},"conversionEvent":{"type":"string","enum":["PURCHASE","LEAD","COMPLETE_REGISTRATION","ADD_TO_CART","INITIATED_CHECKOUT","ADD_PAYMENT_INFO","ADD_TO_WISHLIST","SUBSCRIBE","START_TRIAL","CONTACT","SCHEDULE","SUBMIT_APPLICATION","SEARCH","VIEW_CONTENT","DONATE","FIND_LOCATION","CUSTOMIZE_PRODUCT","OTHER"]},"leadFormId":{"type":"string","pattern":"^\\d+$"},"applicationId":{"type":"string","pattern":"^\\d+$"},"appStoreUrl":{"type":"string","maxLength":2000,"format":"uri"},"specialAdCategories":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["HOUSING","EMPLOYMENT","CREDIT","FINANCIAL_PRODUCTS_SERVICES"]}},"specialAdCategoryCountries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"validateOnly":{"default":false,"type":"boolean"}},"required":["adAccountId","objective","campaignName","creative"],"additionalProperties":false},{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^act_\\d+$"},"pagePostId":{"type":"string","pattern":"^\\d+$"},"dailyBudget":{"type":"number","exclusiveMinimum":0,"maximum":10000},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"campaignName":{"type":"string","minLength":1,"maxLength":200}},"required":["adAccountId","pagePostId","dailyBudget","startDate","endDate","campaignName"],"additionalProperties":false},{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^\\d+$"},"campaignName":{"type":"string","minLength":1,"maxLength":200},"goal":{"type":"string","enum":["traffic","reach","video_views"]},"dailyBudget":{"type":"number","exclusiveMinimum":0,"maximum":10000},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"targeting":{"type":"object","properties":{"locationIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"ageGroups":{"maxItems":6,"type":"array","items":{"type":"string","enum":["AGE_13_17","AGE_18_24","AGE_25_34","AGE_35_44","AGE_45_54","AGE_55_100"]}},"gender":{"type":"string","enum":["GENDER_MALE","GENDER_FEMALE","GENDER_UNLIMITED"]},"languages":{"maxItems":50,"type":"array","items":{"type":"string","minLength":2,"maxLength":10}},"interestCategoryIds":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}}},"required":["locationIds"],"additionalProperties":false},"creative":{"type":"object","properties":{"video":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false}]},"coverImage":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false}]},"adText":{"type":"string","minLength":1,"maxLength":100},"callToAction":{"type":"string","enum":["LEARN_MORE","SHOP_NOW","SIGN_UP","CONTACT_US","DOWNLOAD","BOOK_NOW","ORDER_NOW","WATCH_NOW","GET_QUOTE","APPLY_NOW"]},"landingPageUrl":{"type":"string","format":"uri"}},"required":["video","adText"],"additionalProperties":false},"identity":{"anyOf":[{"type":"object","properties":{"identityId":{"type":"string","minLength":1,"maxLength":100}},"required":["identityId"],"additionalProperties":false},{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":40},"avatar":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false}]}},"required":["displayName","avatar"],"additionalProperties":false}]}},"required":["adAccountId","campaignName","goal","dailyBudget","startDate","endDate","targeting","creative","identity"],"additionalProperties":false},{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^\\d+$"},"campaignName":{"type":"string","minLength":1,"maxLength":200},"goal":{"type":"string","enum":["website_visits","engagement","brand_awareness","video_views"]},"postUrn":{"type":"string","pattern":"^urn:li:(share|ugcPost):\\d+$"},"dailyBudget":{"type":"number","exclusiveMinimum":0,"maximum":10000},"bid":{"type":"number","exclusiveMinimum":0,"maximum":1000},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"targeting":{"type":"object","properties":{"locations":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","pattern":"^urn:li:geo:\\d+$"}},"jobFunctions":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^urn:li:function:\\d+$"}},"seniorities":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^urn:li:seniority:\\d+$"}},"industries":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^urn:li:industry:\\d+$"}},"companySizes":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^urn:li:staffCountRange:\\(\\d+,\\d+\\)$"}},"interfaceLocale":{"default":"en_US","type":"string","pattern":"^[a-z]{2}_[A-Z]{2}$"}},"required":["locations"],"additionalProperties":false},"politicalIntent":{"type":"string","const":"NOT_POLITICAL"}},"required":["adAccountId","campaignName","goal","postUrn","dailyBudget","startDate","endDate","targeting","politicalIntent"],"additionalProperties":false}]},"examples":{"default":{"summary":"Boost a Facebook Page post (created paused)","value":{"adAccountId":"act_1234567890","pagePostId":"1029384756","dailyBudget":10,"startDate":"2026-12-01","endDate":"2026-12-07","campaignName":"Autumn blend boost"}},"metaTraffic":{"summary":"A Meta traffic campaign with a new image ad (created paused)","value":{"adAccountId":"act_1234567890","objective":"traffic","campaignName":"Autumn blend — site visits","budget":{"type":"daily","amount":25},"startDate":"2026-12-01","endDate":"2026-12-14","targeting":{"ageMin":25,"ageMax":54,"locations":{"countries":["US"]},"interests":[{"id":"6003127206524","name":"Coffee"}],"placements":{"publisherPlatforms":["facebook","instagram"],"instagramPositions":["stream","story"]}},"creative":{"type":"image","image":{"uploadId":"facebook/staging/opaque.jpg"},"headline":"Autumn blend is back","body":"Small-batch, roasted this week.","callToAction":"SHOP_NOW","linkUrl":"https://shop.example.com/autumn"},"instagramAccountId":"17841400000000001"}},"metaDryRun":{"summary":"Check a Meta carousel with Meta, creating nothing","value":{"adAccountId":"act_1234567890","objective":"engagement","campaignName":"Autumn range","budget":{"type":"lifetime","amount":300},"startDate":"2026-12-01","endDate":"2026-12-31","targeting":{"locations":{"countries":["US","CA"]}},"creative":{"type":"carousel","body":"Three roasts for the season.","linkUrl":"https://shop.example.com/autumn","cards":[{"image":{"uploadId":"facebook/staging/opaque-1.jpg"},"headline":"Light","linkUrl":"https://shop.example.com/light"},{"image":{"uploadId":"facebook/staging/opaque-2.jpg"},"headline":"Dark","linkUrl":"https://shop.example.com/dark"}]},"validateOnly":true}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"facebookConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metaAdsConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adAccountId":{"type":"string"},"pageId":{"type":"string"},"pagePostId":{"type":["string","null"]},"source":{"type":"string","enum":["page_post","instagram_post","image","video","carousel"]},"objective":{"type":["string","null"]},"idempotencyKey":{"type":"string"},"campaignId":{"type":["string","null"]},"adSetId":{"type":["string","null"]},"creativeId":{"type":["string","null"]},"adId":{"type":["string","null"]},"status":{"type":"string","enum":["pending","paused","active","failed","rolled_back","deleted"]},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","facebookConnectionId","metaAdsConnectionId","adAccountId","pageId","pagePostId","source","objective","idempotencyKey","campaignId","adSetId","creativeId","adId","status","failureReason","createdAt","updatedAt"]},"objects":{"type":"object","properties":{"campaignId":{"type":"string"},"adSetId":{"type":"string"},"creativeId":{"type":"string"},"adId":{"type":"string"}},"required":["campaignId","adSetId","creativeId","adId"]},"videoId":{"type":["string","null"]},"reused":{"type":"object","properties":{"campaign":{"type":"boolean"},"adSet":{"type":"boolean"}},"required":["campaign","adSet"]},"preview":{"anyOf":[{"type":"object","properties":{"format":{"type":"string"},"body":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":["number","null"]},"height":{"type":["number","null"]}},"required":["format","body","url","width","height"]},{"type":"null"}]},"replayed":{"type":"boolean"}},"required":["campaign","objects","preview","replayed"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"tiktokAdsConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"advertiserId":{"type":"string"},"idempotencyKey":{"type":"string"},"campaignId":{"type":["string","null"]},"adGroupId":{"type":["string","null"]},"adId":{"type":["string","null"]},"status":{"type":"string","enum":["pending","paused","active","failed","rolled_back","deleted"]},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","tiktokAdsConnectionId","advertiserId","idempotencyKey","campaignId","adGroupId","adId","status","failureReason","createdAt","updatedAt"]},"objects":{"type":"object","properties":{"campaignId":{"type":"string"},"adGroupId":{"type":"string"},"adId":{"type":"string"}},"required":["campaignId","adGroupId","adId"]},"replayed":{"type":"boolean"}},"required":["platform","accountId","profileId","campaign","objects","replayed"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"linkedinAdsConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adAccountId":{"type":"string"},"idempotencyKey":{"type":"string"},"campaignGroupId":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"creativeId":{"type":["string","null"]},"postUrn":{"type":["string","null"]},"status":{"type":"string","enum":["pending","draft","paused","active","failed","rolled_back","deleted"]},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","linkedinAdsConnectionId","adAccountId","idempotencyKey","campaignGroupId","campaignId","creativeId","postUrn","status","failureReason","createdAt","updatedAt"]},"objects":{"type":"object","properties":{"campaignId":{"type":"string"},"adGroupId":{"type":"string"},"adId":{"type":"string"}},"required":["campaignId","adGroupId","adId"]},"replayed":{"type":"boolean"}},"required":["platform","accountId","profileId","campaign","objects","replayed"]}]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"validateOnly":{"type":"boolean","const":true},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"string","enum":["campaign","ad set","video","creative","ad"]},"result":{"type":"string","enum":["valid","skipped"]},"reason":{"type":"string"}},"required":["step","result"]}}},"required":["platform","accountId","profileId","validateOnly","steps"]}]}}}},"201":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"facebookConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metaAdsConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adAccountId":{"type":"string"},"pageId":{"type":"string"},"pagePostId":{"type":["string","null"]},"source":{"type":"string","enum":["page_post","instagram_post","image","video","carousel"]},"objective":{"type":["string","null"]},"idempotencyKey":{"type":"string"},"campaignId":{"type":["string","null"]},"adSetId":{"type":["string","null"]},"creativeId":{"type":["string","null"]},"adId":{"type":["string","null"]},"status":{"type":"string","enum":["pending","paused","active","failed","rolled_back","deleted"]},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","facebookConnectionId","metaAdsConnectionId","adAccountId","pageId","pagePostId","source","objective","idempotencyKey","campaignId","adSetId","creativeId","adId","status","failureReason","createdAt","updatedAt"]},"objects":{"type":"object","properties":{"campaignId":{"type":"string"},"adSetId":{"type":"string"},"creativeId":{"type":"string"},"adId":{"type":"string"}},"required":["campaignId","adSetId","creativeId","adId"]},"videoId":{"type":["string","null"]},"reused":{"type":"object","properties":{"campaign":{"type":"boolean"},"adSet":{"type":"boolean"}},"required":["campaign","adSet"]},"preview":{"anyOf":[{"type":"object","properties":{"format":{"type":"string"},"body":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":["number","null"]},"height":{"type":["number","null"]}},"required":["format","body","url","width","height"]},{"type":"null"}]},"replayed":{"type":"boolean"}},"required":["campaign","objects","preview","replayed"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"tiktokAdsConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"advertiserId":{"type":"string"},"idempotencyKey":{"type":"string"},"campaignId":{"type":["string","null"]},"adGroupId":{"type":["string","null"]},"adId":{"type":["string","null"]},"status":{"type":"string","enum":["pending","paused","active","failed","rolled_back","deleted"]},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","tiktokAdsConnectionId","advertiserId","idempotencyKey","campaignId","adGroupId","adId","status","failureReason","createdAt","updatedAt"]},"objects":{"type":"object","properties":{"campaignId":{"type":"string"},"adGroupId":{"type":"string"},"adId":{"type":"string"}},"required":["campaignId","adGroupId","adId"]},"replayed":{"type":"boolean"}},"required":["platform","accountId","profileId","campaign","objects","replayed"]},{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"linkedinAdsConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adAccountId":{"type":"string"},"idempotencyKey":{"type":"string"},"campaignGroupId":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"creativeId":{"type":["string","null"]},"postUrn":{"type":["string","null"]},"status":{"type":"string","enum":["pending","draft","paused","active","failed","rolled_back","deleted"]},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","profileId","linkedinAdsConnectionId","adAccountId","idempotencyKey","campaignGroupId","campaignId","creativeId","postUrn","status","failureReason","createdAt","updatedAt"]},"objects":{"type":"object","properties":{"campaignId":{"type":"string"},"adGroupId":{"type":"string"},"adId":{"type":"string"}},"required":["campaignId","adGroupId","adId"]},"replayed":{"type":"boolean"}},"required":["platform","accountId","profileId","campaign","objects","replayed"]}]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/campaigns/{campaignId}":{"patch":{"operationId":"updateCampaign","summary":"Change a Meta campaign's name, budget, bid strategy or spend cap","description":"Meta only. A budget or bid strategy applies to Advantage campaign budget (CBO) campaigns; one that budgets per ad set returns 400, so change it on the ad set. `spendCap: null` removes the cap.","tags":["Ads"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Meta or TikTok campaign id, or LinkedIn campaign group id.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^act_\\d+$"},"name":{"type":"string","minLength":1,"maxLength":200},"budget":{"type":"object","properties":{"type":{"type":"string","enum":["daily","lifetime"]},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1000000}},"required":["type","amount"],"additionalProperties":false},"bidStrategy":{"type":"string","enum":["lowest_cost","bid_cap","cost_cap","min_roas"]},"spendCap":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":10000000},{"type":"null"}]}},"required":["adAccountId"],"additionalProperties":false},"examples":{"default":{"summary":"Raise a Meta CBO campaign's daily budget","value":{"adAccountId":"act_1234567890","budget":{"type":"daily","amount":40}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"campaign":{"type":"object","properties":{"campaignId":{"type":"string"},"updated":{"type":"array","items":{"type":"string"}}},"required":["campaignId","updated"]}},"required":["platform","accountId","adAccountId","campaign"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"deleteCampaign","summary":"Delete a campaign","tags":["Ads"],"parameters":[{"name":"campaignId","in":"path","required":true,"description":"Meta or TikTok campaign id, or LinkedIn campaign group id.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^(act_)?\\d+$"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/ad-groups/{adGroupId}":{"delete":{"operationId":"deleteAdGroup","summary":"Delete a Meta ad set","description":"Meta only. Deletes the ad set and its ads; irreversible.","tags":["Ads"],"parameters":[{"name":"adGroupId","in":"path","required":true,"description":"Meta ad set id, TikTok ad group id, or LinkedIn campaign id.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^act_\\d+$"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"updateAdGroup","summary":"Change an ad set (TikTok ad group, LinkedIn campaign)","description":"Meta: name, daily or lifetime budget (the type it already has), bid, start and end dates, and targeting (which replaces the whole spec). TikTok and LinkedIn: daily budget, end date or name.","tags":["Ads"],"parameters":[{"name":"adGroupId","in":"path","required":true,"description":"Meta ad set id, TikTok ad group id, or LinkedIn campaign id.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^act_\\d+$"},"name":{"type":"string","minLength":1,"maxLength":200},"budget":{"type":"object","properties":{"type":{"type":"string","enum":["daily","lifetime"]},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1000000}},"required":["type","amount"],"additionalProperties":false},"bid":{"type":"object","properties":{"strategy":{"type":"string","enum":["lowest_cost","bid_cap","cost_cap","min_roas"]},"amount":{"type":"number","exclusiveMinimum":0,"maximum":10000},"roasFloor":{"type":"number","exclusiveMinimum":0,"maximum":1000}},"required":["strategy"],"additionalProperties":false},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"targeting":{"type":"object","properties":{"ageMin":{"type":"integer","minimum":13,"maximum":65},"ageMax":{"type":"integer","minimum":13,"maximum":65},"gender":{"default":"all","type":"string","enum":["all","male","female"]},"locations":{"type":"object","properties":{"countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"regions":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}},"cities":{"maxItems":250,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100},"radius":{"type":"integer","minimum":1,"maximum":80},"distanceUnit":{"type":"string","enum":["mile","kilometer"]}},"required":["key"],"additionalProperties":false}},"zips":{"maxItems":2500,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}}},"additionalProperties":false},"excludedLocations":{"type":"object","properties":{"countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"regions":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}},"cities":{"maxItems":250,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100},"radius":{"type":"integer","minimum":1,"maximum":80},"distanceUnit":{"type":"string","enum":["mile","kilometer"]}},"required":["key"],"additionalProperties":false}},"zips":{"maxItems":2500,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}}},"additionalProperties":false},"interests":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200}},"required":["id"],"additionalProperties":false}},"behaviors":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200}},"required":["id"],"additionalProperties":false}},"demographics":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200},"type":{"type":"string","enum":["life_events","family_statuses","industries","income","education_statuses","relationship_statuses","work_positions","work_employers","education_schools","education_majors","user_adclusters"]}},"required":["id","type"],"additionalProperties":false}},"languages":{"maxItems":50,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"customAudiences":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"excludedCustomAudiences":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"placements":{"default":"automatic","anyOf":[{"type":"string","const":"automatic"},{"type":"object","properties":{"publisherPlatforms":{"minItems":1,"type":"array","items":{"type":"string","enum":["facebook","instagram","audience_network","messenger","threads"]}},"facebookPositions":{"type":"array","items":{"type":"string","enum":["feed","right_hand_column","marketplace","video_feeds","story","search","instream_video","facebook_reels","facebook_reels_overlay","profile_feed","notification"]}},"instagramPositions":{"type":"array","items":{"type":"string","enum":["stream","story","explore","explore_home","reels","profile_feed","ig_search","profile_reels"]}},"audienceNetworkPositions":{"type":"array","items":{"type":"string","enum":["classic","rewarded_video"]}},"messengerPositions":{"type":"array","items":{"type":"string","enum":["messenger_home","sponsored_messages","story"]}},"devicePlatforms":{"type":"array","items":{"type":"string","enum":["mobile","desktop"]}}},"required":["publisherPlatforms"],"additionalProperties":false}]},"advantageAudience":{"default":false,"type":"boolean"}},"required":["locations"],"additionalProperties":false}},"required":["adAccountId"],"additionalProperties":false},{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","minLength":1,"maxLength":200},"dailyBudget":{"type":"number","exclusiveMinimum":0,"maximum":10000},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["adAccountId"],"additionalProperties":false},{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","minLength":1,"maxLength":200},"dailyBudget":{"type":"number","exclusiveMinimum":0,"maximum":10000},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["adAccountId"],"additionalProperties":false}]},"examples":{"default":{"summary":"Lower a TikTok ad group's budget","value":{"adAccountId":"7000000000000000001","dailyBudget":20}},"metaBid":{"summary":"Put a cost cap on a Meta ad set","value":{"adAccountId":"act_1234567890","bid":{"strategy":"cost_cap","amount":12}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"adGroup":{"type":"object","properties":{"adGroupId":{"type":"string"},"name":{"type":"string"},"dailyBudget":{"type":"number"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["adGroupId"]}},"required":["platform","accountId","adAccountId","adGroup"]},{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"adGroup":{"type":"object","properties":{"adSetId":{"type":"string"},"updated":{"type":"array","items":{"type":"string"}}},"required":["adSetId","updated"]}},"required":["platform","accountId","adAccountId","adGroup"]}]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/ads/{adId}":{"delete":{"operationId":"deleteAd","summary":"Delete a Meta ad","description":"Meta only. Irreversible; the ad set and campaign stay.","tags":["Ads"],"parameters":[{"name":"adId","in":"path","required":true,"description":"Meta ad id.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^act_\\d+$"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/reach-estimate":{"post":{"operationId":"estimateAdReach","summary":"Estimate a Meta audience's size","description":"Meta only. A read: creates nothing. Bounds are null when Meta cannot estimate, as for some custom audiences.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^act_\\d+$"},"targeting":{"type":"object","properties":{"ageMin":{"type":"integer","minimum":13,"maximum":65},"ageMax":{"type":"integer","minimum":13,"maximum":65},"gender":{"default":"all","type":"string","enum":["all","male","female"]},"locations":{"type":"object","properties":{"countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"regions":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}},"cities":{"maxItems":250,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100},"radius":{"type":"integer","minimum":1,"maximum":80},"distanceUnit":{"type":"string","enum":["mile","kilometer"]}},"required":["key"],"additionalProperties":false}},"zips":{"maxItems":2500,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}}},"additionalProperties":false},"excludedLocations":{"type":"object","properties":{"countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"regions":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}},"cities":{"maxItems":250,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100},"radius":{"type":"integer","minimum":1,"maximum":80},"distanceUnit":{"type":"string","enum":["mile","kilometer"]}},"required":["key"],"additionalProperties":false}},"zips":{"maxItems":2500,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":100}},"required":["key"],"additionalProperties":false}}},"additionalProperties":false},"interests":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200}},"required":["id"],"additionalProperties":false}},"behaviors":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200}},"required":["id"],"additionalProperties":false}},"demographics":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string","maxLength":200},"type":{"type":"string","enum":["life_events","family_statuses","industries","income","education_statuses","relationship_statuses","work_positions","work_employers","education_schools","education_majors","user_adclusters"]}},"required":["id","type"],"additionalProperties":false}},"languages":{"maxItems":50,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"customAudiences":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"excludedCustomAudiences":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"placements":{"default":"automatic","anyOf":[{"type":"string","const":"automatic"},{"type":"object","properties":{"publisherPlatforms":{"minItems":1,"type":"array","items":{"type":"string","enum":["facebook","instagram","audience_network","messenger","threads"]}},"facebookPositions":{"type":"array","items":{"type":"string","enum":["feed","right_hand_column","marketplace","video_feeds","story","search","instream_video","facebook_reels","facebook_reels_overlay","profile_feed","notification"]}},"instagramPositions":{"type":"array","items":{"type":"string","enum":["stream","story","explore","explore_home","reels","profile_feed","ig_search","profile_reels"]}},"audienceNetworkPositions":{"type":"array","items":{"type":"string","enum":["classic","rewarded_video"]}},"messengerPositions":{"type":"array","items":{"type":"string","enum":["messenger_home","sponsored_messages","story"]}},"devicePlatforms":{"type":"array","items":{"type":"string","enum":["mobile","desktop"]}}},"required":["publisherPlatforms"],"additionalProperties":false}]},"advantageAudience":{"default":false,"type":"boolean"}},"required":["locations"],"additionalProperties":false}},"required":["adAccountId","targeting"],"additionalProperties":false},"examples":{"default":{"summary":"Women 25–44 in New York who like coffee","value":{"adAccountId":"act_1234567890","targeting":{"ageMin":25,"ageMax":44,"gender":"female","locations":{"cities":[{"key":"2490299","radius":15,"distanceUnit":"mile"}]},"interests":[{"id":"6003127206524","name":"Coffee"}]}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"estimate":{"type":"object","properties":{"lower":{"type":["number","null"]},"upper":{"type":["number","null"]},"ready":{"type":"boolean"}},"required":["lower","upper","ready"]}},"required":["platform","accountId","adAccountId","estimate"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/instagram-accounts":{"get":{"operationId":"listAdInstagramAccounts","summary":"List the Instagram accounts a Meta ad account can run ads as","description":"Meta only. Pass an `id` as `instagramAccountId` when creating a campaign.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^act_\\d+$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"instagramAccounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]}},"required":["id","username","avatarUrl"]}}},"required":["platform","accountId","adAccountId","instagramAccounts"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/status":{"put":{"operationId":"setAdStatus","summary":"Pause or activate a campaign, ad set (ad group), or ad","description":"LinkedIn: activating a draft campaign group Adeli created activates its creative, campaign and group, in that order.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^act_\\d+$"},"objectId":{"type":"string","pattern":"^\\d+$"},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"level":{"type":"string","enum":["campaign","ad_group","ad"]},"campaignRecordId":{"type":"string","format":"uuid"}},"required":["adAccountId","objectId","status"],"additionalProperties":false},{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^\\d+$"},"objectId":{"type":"string","pattern":"^\\d+$"},"level":{"type":"string","enum":["campaign","ad_group","ad"]},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"campaignRecordId":{"type":"string","format":"uuid"}},"required":["adAccountId","objectId","level","status"],"additionalProperties":false},{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^\\d+$"},"objectId":{"type":"string","pattern":"^\\d+$"},"level":{"type":"string","enum":["campaign","ad_group","ad"]},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"campaignRecordId":{"type":"string","format":"uuid"}},"required":["adAccountId","objectId","level","status"],"additionalProperties":false}]},"examples":{"default":{"summary":"Pause a Meta campaign","value":{"adAccountId":"act_1234567890","objectId":"120200000000000001","status":"PAUSED","level":"campaign"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"objectId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"objectIds":{"type":"array","items":{"type":"string"}}},"required":["platform","accountId","objectId","status"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/targeting":{"get":{"operationId":"listAdTargeting","summary":"Search or list targeting options","description":"Meta: interests, behaviors, demographics, locations and languages, each option's `id` being what a campaign's targeting takes (a location's key, a language's locale id; demographics also need `type`). TikTok: regions, languages, interests. LinkedIn: locations, job_functions, seniorities, industries, company_sizes, each option's `id` being the URN a campaign targets.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^(act_)?\\d+$"}},{"name":"type","in":"query","required":true,"schema":{"anyOf":[{"type":"string","enum":["interests","behaviors","demographics","locations","languages"]},{"type":"string","enum":["regions","languages","interests"]},{"type":"string","enum":["locations","job_functions","seniorities","industries","company_sizes"]}]}},{"name":"goal","in":"query","required":false,"schema":{"type":"string","enum":["traffic","reach","video_views"]},"description":"TikTok: region availability depends on the campaign goal. Defaults to traffic."},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100},"description":"Meta: search by name (required for interests and locations; filters behaviors, demographics and languages). LinkedIn: search locations or industries by name."},{"name":"locationTypes","in":"query","required":false,"schema":{"type":"string"},"description":"Meta locations: comma-separated, from country, region, city, zip. All four when omitted."},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"Meta locations: limit to one country."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok_ads","linkedin_ads"]},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"type":{"type":"string","enum":["regions","languages","interests","locations","job_functions","seniorities","industries","company_sizes"]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parentId":{"type":["string","null"]},"level":{"type":["string","null"]}},"required":["id","name","parentId","level"]}}},"required":["platform","accountId","adAccountId","type","options"]},{"type":"object","properties":{"platform":{"type":"string","const":"meta_ads"},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"type":{"type":"string","enum":["interests","behaviors","demographics","locations","languages"]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":["string","null"]},"locationType":{"type":["string","null"]},"countryCode":{"type":["string","null"]},"region":{"type":["string","null"]},"audienceSizeLower":{"type":["number","null"]},"audienceSizeUpper":{"type":["number","null"]},"path":{"type":"array","items":{"type":"string"}}},"required":["id","name","type"]}}},"required":["platform","accountId","adAccountId","type","options"]}]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ads/identities":{"get":{"operationId":"listAdIdentities","summary":"List TikTok ad identities","description":"TikTok only. The brand name and avatar an ad runs as.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","pattern":"^(act_)?\\d+$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"tiktok_ads"},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"identities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"},"avatarUrl":{"type":["string","null"]}},"required":["id","type","displayName","avatarUrl"]}}},"required":["platform","accountId","adAccountId","identities"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createAdIdentity","summary":"Create a TikTok ad identity","description":"TikTok only.","tags":["Ads"],"parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The Meta Ads (`meta_ads`), TikTok Ads (`tiktok_ads`) or LinkedIn Ads (`linkedin_ads`) account. It names its profile and network, so `profileId` and `platform` can be left out. A Facebook Pages, organic TikTok or organic LinkedIn account id is not accepted."},{"name":"profileId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The profile whose ads account to use, when no `accountId` is given."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["meta_ads","tiktok_ads","linkedin_ads"]},"description":"Needed only when the profile has more than one ad network connected and no `accountId` is given."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string","pattern":"^\\d+$"},"displayName":{"type":"string","minLength":1,"maxLength":40},"avatar":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","minLength":1,"maxLength":200}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false}]}},"required":["adAccountId","displayName","avatar"],"additionalProperties":false},"examples":{"default":{"summary":"A TikTok ad identity","value":{"adAccountId":"7000000000000000001","displayName":"Acme Coffee","avatar":{"uploadId":"tiktok/staging/opaque.jpg"}}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","const":"tiktok_ads"},"accountId":{"type":"string","format":"uuid"},"adAccountId":{"type":"string"},"identity":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"},"avatarUrl":{"type":["string","null"]}},"required":["id","type","displayName","avatarUrl"]}},"required":["platform","accountId","adAccountId","identity"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The connection lacks a permission or provider-confirmed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionRequiredError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The connected account cannot perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"This month's posts, messages and comments","description":"The workspace's sends this UTC month, across all its profiles, against the free tier's allowance: 1,000 posts, 10,000 messages and 10,000 comments per workspace. `limit` is null when the workspace has billing and is never limited. Past the limit, sends answer `402 usage_limit_reached` until `resetsAt` or until a card is added.","tags":["Usage"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string"},"resetsAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"enforced":{"type":"boolean"},"posts":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","limit"]},"messages":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","limit"]},"comments":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["used","limit"]}},"required":["period","resetsAt","enforced","posts","messages","comments"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/usage/x":{"get":{"operationId":"getXUsage","summary":"X API usage for the organization","description":"X API fees are passed through at X's published rates; this totals the organization's usage.","tags":["Usage"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"to":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"ratesAsOf":{"type":"string"},"totalCostMicros":{"type":"number"},"operations":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string"},"resourceType":{"type":"string"},"resourceCount":{"type":"number"},"costMicros":{"type":"number"}},"required":["operation","resourceType","resourceCount","costMicros"]}}},"required":["from","to","ratesAsOf","totalCostMicros","operations"]}}}},"400":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Billing is required: a card is needed to connect more accounts or use X (`billing_required`, `x_billing_required`), or the workspace has used its free monthly allowance (`usage_limit_reached`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Profile, account, or object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Provider quota or rate limit exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Invalid request or provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from Settings → API keys, sent as `Authorization: Bearer <key>`."}},"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"PermissionRequiredError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","const":"permission_required"},"message":{"type":"string"},"details":{"type":"object","properties":{"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky"]},"accountId":{"type":"string"},"profileId":{"type":"string"},"capability":{"type":"string"},"requiredPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"requiredResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"reconnect":{"type":"object","properties":{"action":{"type":"string","const":"restart_oauth"},"method":{"type":"string","const":"POST"},"href":{"type":["string","null"]},"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky"]},"message":{"type":"string"}},"required":["action"]}},"additionalProperties":{}}},"required":["code","message"]}},"required":["error"]},"ApiErrorRecord":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]},"Profile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"externalId":{"type":["string","null"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","externalId","metadata","isDefault","createdAt","updatedAt"]},"ConnectionSession":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"status":{"type":"string","enum":["pending_authorization","processing","pending_page_selection","connected","failed","expired"]},"accountId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"}},"required":["code"]},{"type":"null"}]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"authUrl":{"type":"string","format":"uri"}},"required":["id","profileId","platform","status","accountId","expiresAt","completedAt","error"]},"Account":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"grantedPermissions":{"type":"array","items":{"type":"string"}},"recommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingRecommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"capabilities":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"capabilityRequirements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"requiredPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"requiredResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}}},"required":["requiredPermissions","missingPermissions","requiredResources","missingResources"]}},"reconnect":{"type":"object","properties":{"action":{"type":"string","const":"restart_oauth"},"method":{"type":"string","const":"POST"},"href":{"type":["string","null"]},"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},"required":["action","method","href","provider"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus","grantedPermissions","recommendedPermissions","missingRecommendedPermissions","capabilities","capabilityRequirements","reconnect"]},"NormalizedPost":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"caption":{"type":["string","null"]},"media":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]}},"required":["type","url","thumbnailUrl"]}},"permalink":{"type":["string","null"]},"engagement":{"type":"object","properties":{"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"views":{"type":["number","null"]},"reach":{"type":["number","null"]}},"required":["likes","comments"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"status":{"description":"`scheduled` for a post waiting in a scheduled publication; its `id` is the publication target's id. Optional so clients built before it existed still type-check.","type":"string","enum":["published","scheduled"]},"scheduledFor":{"description":"When a scheduled post goes out.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publicationId":{"description":"The scheduled publication this post belongs to.","anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","platform","accountId","profileId","providerId","caption","media","permalink","engagement","publishedAt"]},"NormalizedMessage":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":["string","null"]},"platform":{"type":"string","enum":["instagram","facebook","whatsapp"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string","enum":["text","template","unsupported"]},"recipient":{"type":["string","null"]},"sender":{"type":["string","null"]},"body":{"type":"string"},"status":{"type":"string"},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"conversationKey":{"description":"`<platform>:<counterparty id>` (an IGSID, a PSID, or a WhatsApp wa_id in digits), scoped to accountId: with accountId it identifies one conversation. Pass it to listMessages to read that conversation. Null when the counterparty is unknown; optional so clients built before it existed still type-check.","type":["string","null"]},"story":{"description":"The Instagram story this message replies to or mentions; null for every other message. Optional so clients built before it existed still type-check.","anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["reply","mention"],"description":"`reply` to one of the account's stories, or a `mention` of the account in someone else's story."},"id":{"description":"The story's id. Pass a reply's story id as storyId to listMessages to read every reply to that story.","type":["string","null"]},"url":{"description":"Instagram's link to the story; it stops working when the story expires.","type":["string","null"]}},"required":["type","id","url"]},{"type":"null"}]}},"required":["id","providerId","platform","accountId","profileId","direction","type","recipient","sender","body","status","occurredAt","createdAt"]},"Publication":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","draft","queued","processing","published","partial","failed","canceled"],"description":"`scheduled` waits for `scheduledFor`; `draft` waits to be published; `canceled` was canceled before it started. Only publications created with `scheduledFor` or `draft` ever have these three."},"progress":{"type":"number","minimum":0,"maximum":1},"scheduledFor":{"description":"When a scheduled publication goes out. Null for one published at once or a draft.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"timeZone":{"description":"The IANA time zone the scheduled time was chosen in, for display.","type":["string","null"]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"statusUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","facebook","tiktok","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","submitting","processing","published","failed","outcome_unknown"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["id","platform","accountId","status","attempts","result","error"]}}},"required":["id","profileId","status","progress","statusUrl","createdAt","updatedAt","completedAt","targets"]},"AccountsAggregate":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"providerId":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayIdentifier":{"type":["string","null"]},"authMethod":{"type":"string","enum":["unified_login","instagram_login","facebook_login"]},"connectionStatus":{"type":"string","enum":["connected","expired","reconnect_required","pending_page_selection","setup_incomplete"]},"grantedPermissions":{"type":"array","items":{"type":"string"}},"recommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingRecommendedPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"capabilities":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"capabilityRequirements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"requiredPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingPermissions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"requiredResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},"missingResources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}}},"required":["requiredPermissions","missingPermissions","requiredResources","missingResources"]}},"reconnect":{"type":"object","properties":{"action":{"type":"string","const":"restart_oauth"},"method":{"type":"string","const":"POST"},"href":{"type":["string","null"]},"provider":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]}},"required":["action","method","href","provider"]}},"required":["id","accountId","profileId","platform","providerId","displayName","displayIdentifier","connectionStatus","grantedPermissions","recommendedPermissions","missingRecommendedPermissions","capabilities","capabilityRequirements","reconnect"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","accounts","errors"]},"PostsAggregate":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","facebook","youtube","x","bluesky","linkedin"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"providerId":{"type":"string"},"caption":{"type":["string","null"]},"media":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"]}},"required":["type","url","thumbnailUrl"]}},"permalink":{"type":["string","null"]},"engagement":{"type":"object","properties":{"likes":{"type":["number","null"]},"comments":{"type":["number","null"]},"shares":{"type":["number","null"]},"views":{"type":["number","null"]},"reach":{"type":["number","null"]}},"required":["likes","comments"]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"status":{"description":"`scheduled` for a post waiting in a scheduled publication; its `id` is the publication target's id. Optional so clients built before it existed still type-check.","type":"string","enum":["published","scheduled"]},"scheduledFor":{"description":"When a scheduled post goes out.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publicationId":{"description":"The scheduled publication this post belongs to.","anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","platform","accountId","profileId","providerId","caption","media","permalink","engagement","publishedAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}}},"required":["status","posts","errors"]},"MessagesAggregate":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":["string","null"]},"platform":{"type":"string","enum":["instagram","facebook","whatsapp"]},"accountId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string","enum":["text","template","unsupported"]},"recipient":{"type":["string","null"]},"sender":{"type":["string","null"]},"body":{"type":"string"},"status":{"type":"string"},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"conversationKey":{"description":"`<platform>:<counterparty id>` (an IGSID, a PSID, or a WhatsApp wa_id in digits), scoped to accountId: with accountId it identifies one conversation. Pass it to listMessages to read that conversation. Null when the counterparty is unknown; optional so clients built before it existed still type-check.","type":["string","null"]},"story":{"description":"The Instagram story this message replies to or mentions; null for every other message. Optional so clients built before it existed still type-check.","anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["reply","mention"],"description":"`reply` to one of the account's stories, or a `mention` of the account in someone else's story."},"id":{"description":"The story's id. Pass a reply's story id as storyId to listMessages to read every reply to that story.","type":["string","null"]},"url":{"description":"Instagram's link to the story; it stops working when the story expires.","type":["string","null"]}},"required":["type","id","url"]},{"type":"null"}]}},"required":["id","providerId","platform","accountId","profileId","direction","type","recipient","sender","body","status","occurredAt","createdAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","tiktok_ads","facebook","meta_ads","whatsapp","youtube","x","bluesky","linkedin","linkedin_ads"]},"accountId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["platform","accountId","code","message"]}},"nextCursor":{"description":"Present only when conversationKey is given: pass it as cursor for the next, older page; null when there are no older messages.","type":["string","null"]}},"required":["status","messages","errors"]}}}}