AdGPT Full Campaign API
The full-campaign API from AdGPT — 5 operation(s) for full-campaign.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/adgpt-com:adgpt-com-full-campaign-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: AdGPT Full Campaign API
version: 1.0.0
description: '# AdGPT API
Generate ready-to-publish ad creatives programmatically: full campaigns, single assets (images, videos, UGC presenter and in-action videos, Google ad copy), post-generation edits, ad recreation, and publishing to your own connected social ad accounts — the same engine that powers app.adgpt.com. **Base URL:** `https://api.adgpt.com/api`
All endpoints live under `/v1`. Responses use a consistent envelope:
```json
{ "success": true, "data": { ... }, "message": "..." }
```
Generation is **asynchronous**: a create call returns immediately with an id; you poll a status endpoint until completion (see *Async jobs* below). Every operation that spends credits declares its cost in this reference (`x-credit-cost`). This document is generated from the committed API contract, which a CI gate keeps in sync with the routes and validation on every change — so the reference cannot silently drift from the implementation. ## Authentication
Authenticate every request with an **API key** in the `Authorization` header:
```
Authorization: Bearer adgpt_... ```
Create and revoke keys from your account settings at app.adgpt.com (Settings → API Keys). The full key is shown **exactly once** at creation — store it securely. Keys inherit your account''s permissions and spend your account''s credits. **401 responses** carry a machine-readable `code`: `UNAUTHENTICATED` (missing/invalid/revoked/expired key), or for first-party JWTs `TOKEN_EXPIRED` (refresh and retry). Repeated failed authentication from one IP is throttled (`429`, code `TOO_MANY_ATTEMPTS`). Keys never work on the first-party web-app endpoints, and key management itself is only available from the logged-in web app — a leaked key cannot mint further keys. If your organization has turned off publishing, share links and the social ad-account endpoints answer **`403` (`ORG_PUBLISHING_BLOCKED`)**. ### You can only access your own resources
Every endpoint is scoped to the account that owns the key. A request for a campaign, asset, brand, catalogue or any other resource that belongs to a different account returns **`404` (`RESOURCE_NOT_FOUND`)** — the same response you get for an id that does not exist, so ids cannot be probed for existence. List endpoints only ever return your own account''s resources. Build your integration against the ids you create and receive back from the API. ## Connect from an AI assistant (MCP)
Everything in this reference is also available as an **MCP (Model Context Protocol) server**, generated from the same API contract — so an AI assistant can drive AdGPT for you instead of you writing HTTP calls. Every operation documented here is an MCP tool with the same inputs, credit costs and async behaviour. **Endpoint:** `https://mcp.adgpt.com/mcp` (Streamable HTTP)
Connecting needs no credentials. A session starts anonymous; sign in (or register) with the account tool inside the conversation, or seed the identity up front by sending `Authorization: Bearer ` on the `initialize` request. Credits bill the signed-in account. Sessions expire after **30 minutes idle** — sign in again afterwards. ### Connecting a client
- **Claude (web/desktop):** Customize → Connectors → Add custom connector → paste the endpoint URL. On Team and Enterprise plans an Owner adds it under Organization settings → Connectors. - **Claude Code:** `claude mcp add --transport http adgpt https://mcp.adgpt.com/mcp`
- **Any other MCP client** that supports remote Streamable HTTP servers: point it at the same URL. ### Discovery
The server publishes a server card at `https://mcp.adgpt.com/.well-known/mcp/server-card.json` and is listed in the official MCP registry as `com.adgpt/adgpt`. ### Working with the tools
Start with `adgpt_capabilities` to search the operation surface or describe one operation''s schema.'
servers:
- url: https://api.adgpt.com/api
security:
- bearerAuth: []
tags:
- name: full-campaign
paths:
/v1/campaigns:
post:
operationId: full-campaign.create
tags:
- full-campaign
summary: Create Full Campaign
description: 'Generate a full multi-asset campaign. Per campaign (platform defaults): 6 image ads (every one with a text overlay; 3 additional text-free variants are rendered behind the scenes solely for the editorial article and are not presented), 4 video ads, 3 UGC presenter videos, 12 Google ad copy variations, 10 keywords, plus social captions. Tier (base/pro/premium) changes price and UGC render quality — NOT asset counts. Product input — exactly ONE mode: (1) crawl: product_url (+optional alternative_product_url fallback); (2) manual: user_instructions.product_name + product_description + ≥1 uploaded_images; (3) text-only: product_name + product_description with no URL and no images. Otherwise 422 MISSING_PRODUCT_INPUT. Upload local product photos first with the adgpt_upload_product_image tool — it returns the S3 url for uploaded_images. brand_id must be a brand you own (auth required) and is never auto-created from the crawled site — create the brand first or pass no_brand. First campaign is free + watermarked. Async — poll with adgpt_job. Optional Idempotency-Key header (8-128 of [A-Za-z0-9_-]): a retry with the same key, query string, and body replays the stored response and does not charge again. A response after a committed charge is stored whatever its status. A 422 is not stored.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
product_url:
type: string
format: uri
maxLength: 10000
description: Product page URL (crawl mode).
alternative_product_url:
type: string
format: uri
maxLength: 10000
description: Fallback URL retried if the primary crawl fails.
visitor_fingerprint:
type: string
maxLength: 128
description: Guest dedup fingerprint (unauthenticated flows).
brand_id:
type: integer
description: ID of a brand you own.
no_brand:
type: boolean
description: Skip brand auto-detection from the URL.
campaign_kind:
type: string
enum:
- standard
- performance
description: Funnel variant. Omit (or standard) for the classic flow; performance adds 3 × 30s commercial videos (currently admin-only while it rolls out).
industry:
type: string
enum:
- books
- wellness
- general
- coaches
- online_course
description: Landing-page industry hint that pins the go-live routing bucket (media_industry) for this campaign. Omit to have it derived from the crawl classifier.
user_instructions:
type: object
properties:
general:
type: string
maxLength: 5000
description: Shared creative brief applied across assets.
general_english:
type: string
maxLength: 5000
description: English translation of the general brief.
original_language:
type: string
maxLength: 10
description: ISO language code of the original brief.
product_name:
type: string
maxLength: 120
description: Product name (manual / text-only input modes).
product_description:
type: string
maxLength: 5000
description: Product description (manual / text-only input modes).
per_asset:
type: object
properties:
image:
type: array
items:
type: object
properties:
instruction:
type: string
maxLength: 2000
description: Scene/visual direction for this image slot.
instruction_original:
type: string
maxLength: 2000
copy:
type: object
properties:
title:
type: string
maxLength: 25
description: On-image overlay title.
subtitle:
type: string
maxLength: 35
cta:
type: string
maxLength: 12
maxItems: 20
description: Per-image-slot direction. copy = on-image text (videos have NO copy).
video:
type: array
items:
type: object
properties:
instruction:
type: string
maxLength: 5000
description: Scene direction for this video slot.
instruction_original:
type: string
maxLength: 5000
maxItems: 10
ugc:
type: array
items:
type: object
properties:
script:
type: string
maxLength: 5000
description: UGC presenter script (required within an entry).
script_original:
type: string
maxLength: 5000
language:
type: string
maxLength: 10
target_duration_sec:
type: integer
description: Target spoken duration.
minimum: 5
maximum: 180
maxItems: 10
uploaded_images:
type: array
items:
type: string
format: uri
maxLength: 2048
maxItems: 5
description: Product image URLs. MUST be S3 chat-upload URLs from AdGPT uploads (…/uploads/chat-product-images/…) — arbitrary external URLs are rejected.
description: Optional customization payload shared by FC and SAC.
parameters:
- name: Idempotency-Key
in: header
required: false
description: 'Optional. 8-128 characters of [A-Za-z0-9_-]. The same key, query string, and JSON body replay the stored response for 24 hours and do not charge again. A different query or body is 422 IDEMPOTENCY_KEY_REUSED. A duplicate while the first request is still running is 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Once a charge has committed, the response is stored whatever its status, including 5xx. If the process dies after the charge, a retry receives 409 IDEMPOTENCY_CHARGED and does not charge again. A replay includes Idempotent-Replayed: true. Responses returned before a charge, and every 422, are not stored.'
schema:
type: string
minLength: 8
maxLength: 128
pattern: ^[A-Za-z0-9_-]{8,128}$
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Envelope'
'401':
description: Missing, invalid, expired or revoked credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Either this Idempotency-Key is already in progress (IDEMPOTENCY_IN_PROGRESS, Retry-After, not stored) or the charge already committed and no final response was stored (IDEMPOTENCY_CHARGED, stored for 24 hours; do not charge again).
headers:
Retry-After:
description: Seconds to wait before retrying this key.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded (see Retry-After header)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-credit-cost: config:full_campaign.user_credit_cost (500 standard / 750 pro / 1500 premium)
x-async:
mode: poll
statusOperationId: full-campaign.status
statusPath: /v1/campaigns/{id}/status
pollHintSeconds: 10
x-rate-limit:
class: generate
requests_per_minute: 10
/v1/campaigns/eligibility:
get:
operationId: full-campaign.eligibility
tags:
- full-campaign
summary: Full Campaign Eligibility
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Envelope'
'401':
description: Missing, invalid, expired or revoked credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded (see Retry-After header)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-rate-limit:
class: general
requests_per_minute: 60
/v1/campaigns/{id}/assets:
get:
operationId: full-campaign.assets
tags:
- full-campaign
summary: Full Campaign Assets
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: grouped
in: query
required: false
schema:
type: boolean
description: Group assets by type.
- name: partial
in: query
required: false
schema:
type: boolean
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Envelope'
'401':
description: Missing, invalid, expired or revoked credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded (see Retry-After header)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-rate-limit:
class: general
requests_per_minute: 60
/v1/campaigns/{id}/download-all:
get:
operationId: full-campaign.download-all
tags:
- full-campaign
summary: Full Campaign Download All
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Envelope'
'401':
description: Missing, invalid, expired or revoked credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded (see Retry-After header)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-rate-limit:
class: general
requests_per_minute: 60
/v1/campaigns/{id}/status:
get:
operationId: full-campaign.status
tags:
- full-campaign
summary: Full Campaign Status
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Envelope'
'401':
description: Missing, invalid, expired or revoked credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded (see Retry-After header)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-rate-limit:
class: general
requests_per_minute: 60
components:
schemas:
Envelope:
type: object
properties:
success:
type: boolean
data: true
message:
type: string
Error:
type: object
properties:
success:
type: boolean
message:
type: string
code:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: AdGPT API key (`adgpt_…`), created from your account settings. First-party JWTs are also accepted.