Appearance
creatives
11 endpoints.
POST /api/v1/creatives/upload-image/{account_id}
Upload Image
Upload an ad image to the account's Meta image library; returns its hash + URL.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/creatives/pages/{account_id}
List Pages
List Facebook Pages + connected Instagram accounts for the ad-creation wizard.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/creatives/ads/{account_id}
List Account Ads
List all ads in an account, pulled live from Meta.
Each ad carries its live delivery status, creative thumbnail and the Facebook Page behind it, so the Ads view can offer Page / status filters without storing ads locally.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/creatives/ads/{account_id}/{ad_id}/status
Update Ad Status
Pause or activate a single ad on Meta.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
ad_id | path | yes | string |
Request body
json
{
"properties": {
"status": {
"type": "string",
"title": "Status"
}
},
"type": "object",
"required": [
"status"
],
"title": "AdStatusUpdate"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/creatives/ads/{account_id}/{ad_id}
Get Ad Detail
Return the full editable setup for one ad, pulled live from Meta.
Flattens the creative's object_story_spec into the same fields the editor (and create_full_ad) speak: identity (page / Instagram), copy, link, CTA and image — so the Edit modal can prefill exactly what Ads Manager shows.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
ad_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/creatives/ads/{account_id}/{ad_id}
Edit Ad
Edit an existing ad on Meta and mirror it locally.
Handles two kinds of change in one call:
- ad-level fields (name, status) → patched directly on the ad;
- the creative (identity, copy, link, CTA, image) → since Meta creatives are immutable, a brand-new creative is built from the supplied fields and swapped onto the ad. This mirrors how Ads Manager "edits" an ad creative.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
ad_id | path | yes | string |
Request body
json
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status"
},
"edit_creative": {
"type": "boolean",
"title": "Edit Creative",
"default": false
},
"page_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Page Id"
},
"instagram_actor_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Instagram Actor Id"
},
"primary_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Primary Text"
},
"headline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Headline"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"link_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Link Url"
},
"call_to_action_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Call To Action Type"
},
"image_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Image Hash"
},
"lead_gen_form_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Lead Gen Form Id"
}
},
"type": "object",
"title": "AdEdit"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}DELETE /api/v1/creatives/ads/{account_id}/{ad_id}
Delete Ad
Delete an ad on Meta and soft-delete any local mirror row.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
ad_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/creatives/ads/{account_id}/{ad_id}/preview
Preview Ad
Return a rendered preview (an <iframe> snippet) for an ad, in the given placement format, fetched live from Meta.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
ad_id | path | yes | string | |
ad_format | query | no | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/creatives/create-ad/{account_id}
Create Full Ad
Create a complete ad on Meta: campaign → ad set → creative → ad.
The ad is created PAUSED by default. Local mirror rows are inserted so the new entities show up in the Creatives list without waiting for a sync.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"campaign_name": {
"type": "string",
"title": "Campaign Name"
},
"objective": {
"type": "string",
"title": "Objective",
"default": "OUTCOME_TRAFFIC"
},
"special_ad_categories": {
"items": {
"type": "string"
},
"type": "array",
"title": "Special Ad Categories",
"default": []
},
"daily_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Daily Budget"
},
"lifetime_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Lifetime Budget"
},
"campaign_budget_optimization": {
"type": "boolean",
"title": "Campaign Budget Optimization",
"default": false
},
"adset_name": {
"type": "string",
"title": "Adset Name"
},
"targeting": {
"properties": {
"geo_locations": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Geo Locations"
},
"age_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Age Min"
},
"age_max": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Age Max"
},
"genders": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Genders"
},
"publisher_platforms": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Publisher Platforms"
},
"facebook_positions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Facebook Positions"
},
"instagram_positions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Instagram Positions"
},
"device_platforms": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Device Platforms"
},
"interests": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Interests"
}
},
"type": "object",
"title": "TargetingSpec"
},
"optimization_goal": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Optimization Goal"
},
"billing_event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Billing Event"
},
"bid_amount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Bid Amount"
},
"bid_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bid Strategy"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Start Time"
},
"end_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "End Time"
},
"ad_name": {
"type": "string",
"title": "Ad Name"
},
"page_id": {
"type": "string",
"title": "Page Id"
},
"instagram_actor_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Instagram Actor Id"
},
"primary_text": {
"type": "string",
"title": "Primary Text"
},
"headline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Headline"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"link_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Link Url"
},
"image_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Image Hash"
},
"call_to_action_type": {
"type": "string",
"title": "Call To Action Type",
"default": "LEARN_MORE"
},
"lead_gen_form_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Lead Gen Form Id"
},
"whatsapp_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Whatsapp Number"
},
"pixel_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pixel Id"
},
"custom_event_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Custom Event Type"
},
"status": {
"type": "string",
"title": "Status",
"default": "PAUSED"
}
},
"type": "object",
"required": [
"campaign_name",
"adset_name",
"targeting",
"ad_name",
"page_id",
"primary_text"
],
"title": "FullAdCreate"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/creatives/create-ad-in-adset/{account_id}
Create Ad In Adset
Create a creative + ad under an ad set that already exists on Meta.
The campaign and ad set are created earlier in the flow (via /adsets); this endpoint only builds the creative and the ad, so an A/B campaign can attach one ad per variant. Created PAUSED by default.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"adset_id": {
"type": "string",
"title": "Adset Id"
},
"ad_name": {
"type": "string",
"title": "Ad Name"
},
"page_id": {
"type": "string",
"title": "Page Id"
},
"instagram_actor_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Instagram Actor Id"
},
"objective": {
"type": "string",
"title": "Objective",
"default": "OUTCOME_TRAFFIC"
},
"primary_text": {
"type": "string",
"title": "Primary Text"
},
"headline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Headline"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"image_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Image Hash"
},
"call_to_action_type": {
"type": "string",
"title": "Call To Action Type",
"default": "LEARN_MORE"
},
"link_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Link Url"
},
"lead_gen_form_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Lead Gen Form Id"
},
"whatsapp_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Whatsapp Number"
},
"status": {
"type": "string",
"title": "Status",
"default": "PAUSED"
}
},
"type": "object",
"required": [
"adset_id",
"ad_name",
"page_id",
"primary_text"
],
"title": "AdInAdSetCreate",
"description": "Create a creative + ad under an ad set that already exists on Meta.\n\nUsed by the Campaign Creator's launch sequence, which creates the campaign\nand ad set(s) up front (via /adsets) and then attaches one ad to each — so\nA/B variants can share a campaign and, optionally, a single creative."
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/creatives/campaign/{campaign_id}
Edit Campaign
Edit an existing campaign (name, status, budget) on Meta and locally.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
Request body
json
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status"
},
"daily_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Daily Budget"
},
"lifetime_budget": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Lifetime Budget"
}
},
"type": "object",
"title": "CampaignEdit"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}