> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrelay.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Campaign
> Create a new ad campaign on one or more connected platforms.
```bash cURL theme={null}
curl -X POST "https://api.adrelay.dev/v1/campaigns" \
-H "X-API-Key: $ADRELAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Summer Sale 2026",
"goal": "CONVERSIONS",
"budget_amount": 50.00,
"budget_period": "DAILY",
"platform": "google_ads"
}'
```
```javascript Node.js theme={null}
const response = await fetch("https://api.adrelay.dev/v1/campaigns", {
method: "POST",
headers: {
"X-API-Key": process.env.ADRELAY_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Summer Sale 2026",
goal: "CONVERSIONS",
budget_amount: 50.0,
budget_period: "DAILY",
platform: "google_ads",
}),
});
const campaign = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.adrelay.dev/v1/campaigns",
headers={
"X-API-Key": "your-api-key-here",
"Content-Type": "application/json",
},
json={
"name": "Summer Sale 2026",
"goal": "CONVERSIONS",
"budget_amount": 50.00,
"budget_period": "DAILY",
"platform": "google_ads",
},
)
campaign = response.json()
```
```json 201 theme={null}
{
"id": "camp_new789",
"platform": "google_ads",
"remote_id": "555666777",
"name": "Summer Sale 2026",
"status": "PAUSED",
"goal": "CONVERSIONS",
"budget_amount": 50.00,
"budget_period": "DAILY",
"currency": "USD",
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-21T10:00:00Z"
}
```
```json 400 theme={null}
{
"error": "Validation failed.",
"code": "VALIDATION_ERROR",
"timestamp": 1711036800,
"request_id": "req_def456",
"details": [
{ "field": "budget_amount", "message": "Must be greater than 0." }
]
}
```
```json 403 theme={null}
{
"error": "No active connection for platform google_ads.",
"code": "FORBIDDEN",
"timestamp": 1711036800,
"request_id": "req_ghi789"
}
```
Campaigns are created with a status of `PAUSED` by default. Use the [Update Campaign](/api-reference/campaigns/update) endpoint to set the status to `ACTIVE` when ready.
For creating campaigns across multiple platforms simultaneously, use the `targets` array instead of `platform`. See the [Multi-Platform Campaigns](/guides/multi-platform-campaigns) guide for details.
## OpenAPI
````yaml POST /v1/campaigns
openapi: 3.1.0
info:
title: Adrelay API
version: 0.1.0
description: >-
Unified Ad Platform API — proxy and normalize campaigns across Google Ads,
Meta, TikTok, and more.
servers:
- url: https://api.adrelay.dev/v1
description: Production
- url: http://localhost:3001
description: Local
security: []
paths:
/v1/campaigns:
post:
summary: Create campaign
description: >-
Creates a campaign on one or more platforms. Send a single
platform/organization_id for single-platform creation, or a targets[]
array for multi-platform fan-out.
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
properties:
name:
type: string
minLength: 1
maxLength: 255
budget_amount:
type: number
budget_period:
$ref: '#/components/schemas/AdsBudgetPeriod'
currency:
type: string
default: USD
goal:
$ref: '#/components/schemas/AdsCampaignGoalType'
start_at:
type:
- string
- 'null'
end_at:
type:
- string
- 'null'
targets:
type: array
items:
type: object
properties:
platform:
$ref: '#/components/schemas/Platform'
organization_id:
type: string
minLength: 1
required:
- platform
- organization_id
minItems: 1
maxItems: 10
required:
- name
- budget_amount
- budget_period
- goal
- targets
- type: object
properties:
name:
type: string
minLength: 1
maxLength: 255
budget_amount:
type: number
budget_period:
$ref: '#/components/schemas/AdsBudgetPeriod'
currency:
type: string
default: USD
goal:
$ref: '#/components/schemas/AdsCampaignGoalType'
start_at:
type:
- string
- 'null'
end_at:
type:
- string
- 'null'
platform:
$ref: '#/components/schemas/Platform'
organization_id:
type: string
minLength: 1
required:
- name
- budget_amount
- budget_period
- goal
- platform
- organization_id
responses:
'201':
description: Campaign created (single-platform) or multi-platform results
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignResponse'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- apiKey: []
components:
schemas:
AdsBudgetPeriod:
type: string
enum:
- DAILY
- MONTHLY
- TOTAL
- LIFETIME
AdsCampaignGoalType:
type: string
enum:
- UNSPECIFIED
- BRAND_AWARENESS
- REACH
- WEBSITE_TRAFFIC
- LEADS
- SALES
- APP_PROMOTION
Platform:
type: string
enum:
- GOOGLE
- META
- TIKTOK
- LINKEDIN
- PINTEREST
- REDDIT
CreateCampaignResponse:
type: object
properties:
data:
$ref: '#/components/schemas/AdsCampaign'
required:
- data
ErrorEnvelope:
type: object
properties:
error:
type: object
properties:
code:
$ref: '#/components/schemas/ErrorCode'
message:
type: string
platform:
type: string
retryable:
type: boolean
requestId:
type: string
format: uuid
platformError:
$ref: '#/components/schemas/PlatformErrorDetail'
required:
- code
- message
- retryable
- requestId
required:
- error
AdsCampaign:
type: object
properties:
id:
type: string
platform:
$ref: '#/components/schemas/Platform'
organization_id:
type: string
name:
type: string
status:
$ref: '#/components/schemas/AdsStatus'
goal:
$ref: '#/components/schemas/AdsCampaignGoalType'
budget_amount:
type: number
budget_period:
$ref: '#/components/schemas/AdsBudgetPeriod'
currency:
type: string
total_spend_amount:
type: number
start_at:
type:
- string
- 'null'
end_at:
type:
- string
- 'null'
created_at:
type:
- string
- 'null'
updated_at:
type:
- string
- 'null'
raw:
type: object
additionalProperties: {}
required:
- id
- platform
- organization_id
- name
- status
ErrorCode:
type: string
enum:
- BAD_REQUEST
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- CONFLICT
- RATE_LIMITED
- RATE_LIMIT_EXCEEDED
- PLATFORM_ERROR
- NOT_SUPPORTED
- TOKEN_EXPIRED
- INTERNAL_ERROR
PlatformErrorDetail:
type: object
properties:
code:
type: string
message:
type: string
field:
type: string
required:
- message
AdsStatus:
type: string
enum:
- UNSPECIFIED
- ACTIVE
- PAUSED
- ARCHIVED
- DRAFT
- SCHEDULED_FOR_DELETION
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
````