Quick Start
1. Get your API key
Sign up and create an API key from your dashboard.
2. Configure your MCP client
Add Advuna to your Claude Desktop or MCP-compatible client:
{
"mcpServers": {
"advuna": {
"url": "https://advuna.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}3. Start creating
Ask Claude to create ad creatives from any website URL!
Authentication
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer adv_your_api_key_here
API keys start with adv_ and should be kept secret. Never commit them to version control.
Human Intervention Required
Some operations require a human to complete the action in a browser:
| Action | Tool | Human Must Do |
|---|---|---|
| Upgrade to Pro | advuna_get_checkout_url | Complete payment in browser |
| Connect Reddit | advuna_get_reddit_connect_url | Authorize in Reddit website |
Note: Lost API keys can be recovered via email using advuna_request_key_recovery + advuna_complete_key_recovery.
If the AI agent has email access, this flow is fully automated.
Available Tools (30)
Account Tools
advuna_get_account
Get current user account information, subscription status, and usage limits
advuna_create_account
Create a new Advuna account. Returns an API key. No auth required.
email
*
|
string | Email address |
password
*
|
string | Password (min 6 chars) |
advuna_list_api_keys
List all API keys for your account (shows prefix only, not full key)
advuna_regenerate_api_key
Generate a new API key. Optionally revoke an existing key.
name
*
|
string | Name for the new key |
revoke_prefix
|
string | Revoke key with this prefix |
advuna_request_key_recovery
Request a recovery code to generate a new API key. No auth required.
email
*
|
string | Email address of the account |
advuna_complete_key_recovery
Complete key recovery with email code. Returns new API key. No auth required.
email
*
|
string | Email address of the account |
code
*
|
string | 6-digit recovery code from email |
advuna_get_reddit_status
Check if a Reddit account is connected
advuna_get_reddit_connect_url
Get the OAuth URL to connect a Reddit Ads account
advuna_get_checkout_url
Get the Paddle checkout URL to upgrade subscription
plan
|
string | 'monthly' or 'yearly' (default: monthly) |
Project Tools
advuna_create_project
Create a new project from a URL. Scrapes website, extracts brand, generates copy.
url
*
|
string | Website URL to scrape |
name
|
string | Optional project name |
advuna_list_projects
List all projects
page
|
integer | Page number (default: 1) |
per_page
|
integer | Results per page (default: 20) |
status
|
string | Filter by status |
advuna_get_project
Get full project details including brand, copy, and creative counts
project_id
*
|
integer | Project ID |
advuna_update_brand
Update brand settings (name, slogan, colors) and confirm brand
project_id
*
|
integer | Project ID |
brand_name
|
string | Brand name |
slogan
|
string | Slogan/tagline |
brand_colors
|
array | Hex color codes |
confirm
|
boolean | Confirm brand (default: true) |
advuna_delete_project
Delete a project and all associated data
project_id
*
|
integer | Project ID |
Creative Tools
advuna_generate_creatives
Trigger creative generation for a project
project_id
*
|
integer | Project ID |
templates
|
array | Specific templates to generate |
sizes
|
array | Specific sizes to generate |
advuna_list_creatives
List all creatives for a project
project_id
*
|
integer | Project ID |
template
|
string | Filter by template |
status
|
string | Filter by status |
advuna_get_creative
Get details of a specific creative
project_id
*
|
integer | Project ID |
creative_id
*
|
integer | Creative ID |
advuna_regenerate_creative
Re-render a specific creative
project_id
*
|
integer | Project ID |
creative_id
*
|
integer | Creative ID |
advuna_update_creative
Update creative copy selection
project_id
*
|
integer | Project ID |
creative_id
*
|
integer | Creative ID |
headline_id
|
integer | Headline copy ID |
description_id
|
integer | Description copy ID |
cta_id
|
integer | CTA copy ID |
advuna_delete_creative
Delete a specific creative
project_id
*
|
integer | Project ID |
creative_id
*
|
integer | Creative ID |
Campaign Tools
advuna_get_suggested_subreddits
Get AI-powered subreddit suggestions for targeting
project_id
*
|
integer | Project ID |
limit
|
integer | Number of suggestions (default: 10) |
advuna_validate_subreddits
Validate subreddits exist and allow advertising
subreddits
*
|
array | Array of subreddit names |
advuna_create_campaign
Create a new Reddit advertising campaign
project_id
*
|
integer | Project ID |
creative_id
*
|
integer | Creative ID to use |
headline
*
|
string | Campaign headline (max 100 chars) |
destination_url
*
|
string | Click-through URL |
daily_budget
*
|
float | Daily budget in USD (min $5) |
subreddits
*
|
array | Target subreddits |
advuna_list_campaigns
List all campaigns
project_id
|
integer | Filter by project |
status
|
string | Filter by status |
advuna_get_campaign
Get campaign details with metrics
campaign_id
*
|
integer | Campaign ID |
advuna_pause_campaign
Pause an active campaign
campaign_id
*
|
integer | Campaign ID |
advuna_resume_campaign
Resume a paused campaign
campaign_id
*
|
integer | Campaign ID |
advuna_update_campaign
Update campaign budget and targeting
campaign_id
*
|
integer | Campaign ID |
daily_budget
|
float | New daily budget |
subreddits
|
array | New target subreddits |
advuna_get_campaign_stats
Get detailed campaign metrics
campaign_id
*
|
integer | Campaign ID |
start_date
|
string | Start date (YYYY-MM-DD) |
end_date
|
string | End date (YYYY-MM-DD) |
Job Tools
advuna_get_job_status
Check the status of an async job (project, creatives, campaign)
job_id
*
|
string | Job ID (e.g., 'project_123') |
Response Format
Success Response
{
"success": true,
"data": {
"project_id": 123,
"status": "scraping"
},
"message": "Project created successfully"
}Async Operation
{
"success": true,
"data": {
"job_id": "project_123",
"status": "processing"
},
"message": "Poll advuna_get_job_status to check progress."
}Error Response
{
"success": false,
"error": {
"code": "limit_exceeded",
"message": "Free plan limited to 1 project.",
"action": "Upgrade to Pro for unlimited."
}
}Error Codes
| Code | Description |
|---|---|
| unauthorized | Invalid or missing API key |
| forbidden | Action not allowed for this user |
| not_found | Resource does not exist |
| validation_error | Invalid parameters |
| limit_exceeded | Usage limit reached |
| reddit_not_connected | Reddit account not linked |
| subscription_required | Feature requires paid plan |
| rate_limited | Too many requests |
Rate Limits
- 100 requests/minute - General operations
- 10 requests/minute - Expensive operations (create_project, generate_creatives, create_campaign)
- 3 requests/hour - Key recovery operations (request_key_recovery, complete_key_recovery)
Rate limits are per API key (or IP for unauthenticated endpoints). Exceeding limits returns a 429 status with a Retry-After header.
Example Workflow
-
1
Create a project
advuna_create_project(url: "https://example.com") -
2
Poll for completion
advuna_get_job_status(job_id: "project_123") -
3
Confirm brand settings
advuna_update_brand(project_id: 123, confirm: true) -
4
Generate creatives
advuna_generate_creatives(project_id: 123) -
5
Launch Reddit campaign
advuna_create_campaign(project_id: 123, creative_id: 456, ...)