---
title: "Create a ChatGPT Ads chat card ad"
method: POST
path: "/api/v1/tools/chatgpt_create_ad/execute"
tags: ["ChatGPT Ads"]
---

# Create a ChatGPT Ads chat card ad

`POST /api/v1/tools/chatgpt_create_ad/execute`

## Request

- Base URL: `https://adako.ai`
- URL: `https://adako.ai/api/v1/tools/chatgpt_create_ad/execute`
- Auth: HTTP bearer

Adds one paused chat card ad to an ad group that already exists: the image is downloaded, checked and uploaded, then the ad is created. Nothing delivers and nothing spends until the user resumes it.
Use when: the user wants another creative in a structure they already have — a second headline to test, a replacement for a rejected ad. Get the ad group id from chatgpt_list_ad_groups.
Do not use it to build a campaign from nothing: that is chatgpt_launch_ad. Do not invent copy, a destination or an image the user did not give; if any of the four is missing, ask.
The limits are hard and checked before anything is created, so a rejection here costs nothing: the title must be 3–50 characters, the body at most 100, the destination an https URL, and the image square. Run chatgpt_validate_chat_card first if you want to check copy for free.
Returns the new ad id, read back from the platform with its paused state and its review verdict. A new ad always starts in review; it delivers nothing until the platform approves it, so do not tell the user it is live until chatgpt_list_ads says approved.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `arguments` object, required
    - `ad_account_id` string: ChatGPT Ads advertiser account id. One advertiser key belongs to one account, so this is only needed when the user has connected more than one key. Omit it to use the primary account.
    - `ad_group_id` string, required: The ad group to add the ad to, from chatgpt_list_ad_groups.
    - `title` string, required: Chat card headline, 3–50 characters. This is the line people read first.
    - `body` string, required: Chat card body copy, at most 100 characters. Put the offer in the first half.
    - `target_url` string, uri, required: Where a click goes. Must be https and reachable without a login.
    - `image_url` string, uri, required: The card image. It must be square; its bytes are checked here before anything is created. Adako hosts no files: the platform downloads this URL itself, from its own servers and often hours later, so it must be a public link straight to the file — not a file on the computer, not a Drive, Dropbox or design-tool share page, not a link that expires or asks for a login. Call check_media first: it repairs the usual share links, checks the file against this platform, and says where to put a file that has no link yet.
    - `name` string: Ad name in Ads Manager. Defaults to the headline.
    - `idempotency_key` string: Optional caller-supplied key; identical keys never execute twice.
    - `raw_data` boolean: Return compact JSON only (no markdown). Use when you will compute on the result.

## Response `200`

The tool ran. A write returns proposal_id and approve_url while the change waits for approval.

- SuccessEnvelope
  - `success` unknown, required
  - `tool` string, required
  - `data` object, required: Machine-readable result.
  - `markdown` string, required: The same result written for a person or a model.
  - `quota` Quota: Task usage for the current billing period.
    - `plan` string
    - `used` integer
    - `limit` integer
    - `period_end` string
    - `upgrade_url` string
  - `proposal_id` string: Present for writes. Nothing changes on the ad platform until it is approved.
  - `approve_url` string: Where a person approves the proposal.
  - `request_id` string, required

## Other responses

- `400`: Invalid arguments, or the ad account could not be resolved.
- `401`: Missing, invalid, revoked or expired API key.
- `402`: Monthly task quota used up, or the plan does not include this tool.
- `403`: The connected ad account lacks the access level this tool needs.
- `404`: Unknown tool name.
- `409`: Not connected, reconnect needed, confirmation required, a proposal already pending or no longer pending, an identical create that failed earlier today (proposal_failed_before), a create that duplicates an approved one (duplicate_create), the ad-account limit of the plan reached (account_limit), or an Idempotency-Key reused with different arguments.
- `429`: Rate limited by Adako or by the ad platform. See Retry-After.
- `500`: Unexpected error inside Adako.
- `502`: The ad platform returned an error.

---

[API](https://skmtc.dev/adako/apis/adako-rest-api.md) · [All operations](https://skmtc.dev/adako/apis/adako-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adako/apis/adako-rest-api/revisions/59ee60d48a56?raw)