{"openapi":"3.1.0","info":{"title":"FB Ads API","version":"1.0.0","description":"Create asynchronous Meta Ad Library collection tasks, inspect results, and automate delivery with webhooks and schedules."},"servers":[{"url":"/","description":"Current deployment"}],"tags":[{"name":"Tasks"},{"name":"Archive"},{"name":"Webhooks"},{"name":"Schedules"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/tasks":{"post":{"tags":["Tasks"],"summary":"Create a collection task","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRequest"}}}},"responses":{"202":{"description":"Task accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAccepted"}}}},"402":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/tasks/from_url":{"post":{"tags":["Tasks"],"summary":"Create a task from a Meta Ad Library URL","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"count":{"type":"integer","minimum":1,"maximum":50000,"default":50},"eu_data":{"type":"boolean","default":false}}}}}},"responses":{"202":{"description":"Task accepted"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/tasks/{uuid}/status":{"get":{"tags":["Tasks"],"summary":"Get task status","parameters":[{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"Task status"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/tasks/{uuid}/results":{"get":{"tags":["Tasks"],"summary":"Get paginated task results","parameters":[{"$ref":"#/components/parameters/TaskId"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Result page"},"409":{"$ref":"#/components/responses/Error"}}}},"/v1/tasks/{uuid}/coverage":{"get":{"tags":["Tasks"],"summary":"Inspect collection coverage","parameters":[{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"Coverage details"}}}},"/v1/tasks/{uuid}/stop":{"post":{"tags":["Tasks"],"summary":"Stop a running task","parameters":[{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"Cancellation requested"},"409":{"$ref":"#/components/responses/Error"}}}},"/v1/archive/ads":{"get":{"tags":["Archive"],"summary":"Search observed ads","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"advertiser_id","in":"query","schema":{"type":"string"}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"Observed ad page"}}}},"/v1/archive/ads/{providerId}/timeline":{"get":{"tags":["Archive"],"summary":"Get the observation timeline for an ad","parameters":[{"name":"providerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Observation timeline"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/archive/ads/{providerId}/media":{"get":{"tags":["Archive"],"summary":"Get observed media references for an ad","parameters":[{"name":"providerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Media references"}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","responses":{"200":{"description":"Webhook list"}}},"post":{"tags":["Webhooks"],"summary":"Create webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["run.completed","run.failed","run.progress"]}},"filters":{"type":"object"}}}}}},"responses":{"201":{"description":"Webhook and one-time signing secret"}}}},"/v1/schedules":{"get":{"tags":["Schedules"],"summary":"List schedules","responses":{"200":{"description":"Schedule list"}}},"post":{"tags":["Schedules"],"summary":"Create schedule","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","interval_seconds","request"],"properties":{"name":{"type":"string"},"interval_seconds":{"type":"integer","minimum":300},"request":{"$ref":"#/components/schemas/TaskRequest"},"partition_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"}}}}}}},"responses":{"201":{"description":"Created schedule"}}}},"/v1/webhooks/{webhookId}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/schedules/{scheduleId}":{"delete":{"tags":["Schedules"],"summary":"Delete a schedule","parameters":[{"name":"scheduleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Reuse the same value when retrying a request."},"TaskId":{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"TaskRequest":{"type":"object","properties":{"q":{"type":"string","maxLength":200},"advertiser_id":{"type":"string","pattern":"^\\d+$"},"country":{"type":"string","pattern":"^(?:[A-Za-z]{2}|ALL)$"},"count":{"type":"integer","minimum":1,"maximum":50000,"default":50},"ad_type":{"type":"string","enum":["all","political_and_issue_ads","housing_ads","credit_ads"],"default":"all"},"active_status":{"type":"string","enum":["active","inactive","all"]},"media_type":{"type":"string","enum":["all","image","video","meme"],"default":"all"},"publisher_platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","messenger","audience_network","whatsapp"]}},"content_languages":{"type":"array","items":{"type":"string"}},"eu_data":{"type":"boolean","default":false}},"description":"Provide exactly one of q or advertiser_id. country is required for keyword search."},"TaskAccepted":{"type":"object","required":["task_id","status"],"properties":{"task_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"message":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}}}}}