API docs by Redocly

SearchAtlas API (1.0.0)

Download OpenAPI specification:

URL: https://searchatlas.com

SearchAtlas API Documentation

Each service has its own base URL. All endpoints require X-API-Key header.

Get your key at Dashboard - API Settings.

Core: Overview

Core platform APIs for customer account management, authentication, team management, billing, subscriptions, and project configuration.

Base URL: https://api.searchatlas.com

Core: Projects

Customer project management - create, list, update, delete projects and connect external app IDs

List projects

Returns all projects for the authenticated customer. Includes app data, AI summary status, and linked app IDs.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

Create project

Creates a new project for the authenticated customer. Validates domain uniqueness per customer (normalized, ignoring www. prefix). Optionally skips AI Agent project creation via create_ai_agent_project: false. Triggers AI summary generation on staging when enabled.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 200 characters
description
string
is_active
boolean
Default: true
timezone
string

IANA timezone string (e.g. America/New_York)

object (PlatformsConfig)
default_approval_type
string
Enum: "AUTO_PUBLISH" "APPROVE_IF_IMAGE" "AI_IMAGES_ONLY" "APPROVE_FOR_PUBLISH"
default_image_source_type
string or null
object (AISettings)
image_prompt
string <= 1000 characters

Convenience alias - merged into ai_settings.image_prompt on save

Responses

Request samples

Content type
application/json
{
  • "domain_url": "https://example.com",
  • "country_code": "US",
  • "keywords": [
    ],
  • "create_ai_agent_project": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get project by ID

Returns a single project with full app data, AI summary, and linked app IDs.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Partial update project

Updates specified fields on a project. Accepts the same fields as create.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keywords
Array of strings
competitors
Array of strings
is_starred
boolean
custom_report_apps
Array of strings
country_code
string
location
string or null
location_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "keywords": [
    ],
  • "competitors": [
    ],
  • "is_starred": true,
  • "custom_report_apps": [
    ],
  • "country_code": "string",
  • "location": "string",
  • "location_id": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete project

Permanently deletes a project and all associated data.

Authorizations:
apiKeyAuth

Responses

Get project status

Returns the current status and in-progress app sync status for a project.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "in_progress": [
    ]
}

Connect external app to project

Links an external app ID to an existing project. Supported apps: sa, se, krt, otto, gbp, local_seo, otto_v2, llmv, otto_ppc.

  • UUID-format IDs for llmv
  • Integer IDs for sa, se, krt, otto, otto_v2, local_seo
  • String IDs for gbp, otto_ppc
Authorizations:
apiKeyAuth
path Parameters
projectId
required
integer
Request Body schema: application/json
required
app
required
string
Enum: "sa" "se" "krt" "otto" "gbp" "local_seo" "otto_v2" "llmv" "otto_ppc"

App key to connect

app_id
string

External app ID. Integer for most apps; UUID for llmv; string for gbp/otto_ppc.

keywords
Array of strings

Responses

Request samples

Content type
application/json
{
  • "app": "se",
  • "app_id": "12345",
  • "keywords": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Core: Customer Reports (legacy)

Legacy customer-level report portfolio endpoints (pre-RB v1 paths)

List customer clients

Returns all customer client accounts accessible to the authenticated user.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Core: Quota

Quota and credit usage logs

List quota logs

Returns quota/credit usage history for the authenticated customer. Results are read-only and may be served from ClickHouse (analytics) or PostgreSQL (legacy). Includes quota_display_name for human-readable descriptions.

Authorizations:
apiKeyAuth
query Parameters
quota_name
string

Filter by quota name slug

operation_type
string

Filter by operation type

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

Core: Indexing

Google indexing batch submission and tracking

List indexing batches

Returns all indexing batches for the authenticated customer. Includes is_report_available flag (true if batch is 8+ days old and has results), indexer_submitted_links, indexer_indexed_links, and indexation_percentage.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download indexing report

Returns a downloadable report for a completed indexing batch.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
No sample

Get batch history

Returns the status history and timeline for an indexing batch.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{ }

Submit indexing batch

Creates and submits a new indexing batch. Accepts 1-1000 URLs per batch. Each URL must be a valid string up to 2000 characters.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 255 characters
urls_to_send
required
Array of strings [ 1 .. 1000 ] items [ items <= 2000 characters ]

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "string",
  • "indexing_links": [
    ]
}

Content Assistant: Overview

AI-powered content creation and optimization platform. Create SEO-optimized articles with AI, manage Brand Vaults for brand voice consistency, run content audits, use CGenius for advanced content generation pipelines, manage Domain Knowledge Networks, and publish to WordPress or external CMS platforms.

Base URL: https://ca.searchatlas.com

Content Assistant: Pages

Create, list, retrieve, update, and delete content optimizer pages (articles)

List all pages

Returns a paginated list of articles/pages for the authenticated user's account. Supports filtering by status, project, brand vault, and ordering.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 10
search
string

Search by title or URL

ordering
string

Field to sort by. Prefix with - for descending. E.g. -created_at

status
string
Enum: "draft" "in_progress" "ready_to_publish" "published" "archived"

Filter by article status

project
integer

Filter by project ID

brand_vault_uuid
string <uuid>

Filter by Brand Vault UUID

is_repolling
boolean
Default: false

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create a new page

Creates a new article. Optionally crawls a target URL for content, accepts a keywords list and location for SEO scoring, and can trigger AI outline generation immediately.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
title
string
target_url
string <uri>

Live URL to crawl for existing content

keywords_list
Array of strings

Initial target keywords

country_code
string

ISO alpha-2 country code for keyword scoring

location
string

Named location (city/region) - takes priority over country_code

location_id
integer

Location ID paired with location string

should_use_headless_browser
boolean
Default: false
should_generate_outline
boolean
Default: false

Immediately trigger AI outline generation after creation

mode_of_creation
string
Default: "ai"
Enum: "ai" "manual"
brand_vault_uuid
string <uuid>

Associate with a Brand Vault for AI settings and context

project_name
string

Assign to an existing project by name

language
string

ISO 639-1 language code

Responses

Request samples

Content type
application/json
{
  • "title": "Best Running Shoes 2025",
  • "target_url": "https://example.com/running-shoes",
  • "keywords_list": [
    ],
  • "country_code": "us",
  • "mode_of_creation": "ai"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "id": 0,
  • "title": "string",
  • "url": "http://example.com",
  • "status": "draft",
  • "score": 0,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability_grade": "string",
  • "readability_grade_range": "string",
  • "version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "project_id": 0,
  • "project_name": "string",
  • "brand_vault": {
    },
  • "due_date": "2019-08-24",
  • "tags": [
    ],
  • "assigned_to_users": [
    ],
  • "imported_from_url": "http://example.com",
  • "wp_synced": true,
  • "wp_syncing_task_status": "string",
  • "language": "string",
  • "feature_image": "http://example.com",
  • "feature_image_alt_text": "string",
  • "was_deleted": true
}

Get pages summary statistics

Returns aggregate counts of articles grouped by status for the authenticated account.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "draft": 0,
  • "in_progress": 0,
  • "ready_to_publish": 0,
  • "published": 0
}

Bulk update pages

Update shared fields (due_date, status, assigned_to_users, project_name, brand_vault_uuid) across multiple pages at once.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
required
Array of strings <uuid> [ items <uuid > ]
required
object

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ],
  • "data": {
    }
}

Bulk delete pages

Soft-deletes multiple pages by UUID list.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
required
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ]
}

Get page by UUID

Returns full page data including editor state, cleaned HTML, keyword data, and WP fields.

Authorizations:
apiKeyAuth
query Parameters
is_repolling
boolean

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "id": 0,
  • "title": "string",
  • "url": "http://example.com",
  • "status": "draft",
  • "score": 0,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability_grade": "string",
  • "readability_grade_range": "string",
  • "version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "project_id": 0,
  • "project_name": "string",
  • "brand_vault": {
    },
  • "due_date": "2019-08-24",
  • "tags": [
    ],
  • "assigned_to_users": [
    ],
  • "imported_from_url": "http://example.com",
  • "wp_synced": true,
  • "wp_syncing_task_status": "string",
  • "language": "string",
  • "feature_image": "http://example.com",
  • "feature_image_alt_text": "string",
  • "was_deleted": true,
  • "editor_state": "string",
  • "cleaned_html": "string",
  • "is_cleaned_html_updated": true,
  • "text_preview": "string",
  • "readability": "string",
  • "average_readability": 0,
  • "suggested_word_count_limits": {
    },
  • "country_code": "string",
  • "onpage_audit_country_code": "string",
  • "location": "string",
  • "location_id": 0,
  • "status_code": 0,
  • "hostname": "string",
  • "meta_title": "string",
  • "meta_desc": "string",
  • "hero_image": "http://example.com",
  • "hero_image_alt_text": "string",
  • "score_extended": { },
  • "score_counts": { },
  • "created_by_user": "string",
  • "wp_post_status": "string",
  • "wp_post_type": "string",
  • "wp_synced_at": "2019-08-24T14:15:22Z",
  • "wp_post_categories": [
    ],
  • "wp_post_author_id": 0,
  • "wp_sync_at_date": "2019-08-24",
  • "wp_sync_at_time": "string",
  • "wp_published_at_url": "http://example.com",
  • "permalink": "string",
  • "applied_refiners": [
    ],
  • "should_use_headless_browser": true
}

Update page hostname

Full update of a page. Primarily used to update the associated hostname.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
hostname
string

Domain hostname to associate with this page

Responses

Request samples

Content type
application/json
{
  • "hostname": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "id": 0,
  • "title": "string",
  • "url": "http://example.com",
  • "status": "draft",
  • "score": 0,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability_grade": "string",
  • "readability_grade_range": "string",
  • "version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "project_id": 0,
  • "project_name": "string",
  • "brand_vault": {
    },
  • "due_date": "2019-08-24",
  • "tags": [
    ],
  • "assigned_to_users": [
    ],
  • "imported_from_url": "http://example.com",
  • "wp_synced": true,
  • "wp_syncing_task_status": "string",
  • "language": "string",
  • "feature_image": "http://example.com",
  • "feature_image_alt_text": "string",
  • "was_deleted": true,
  • "editor_state": "string",
  • "cleaned_html": "string",
  • "is_cleaned_html_updated": true,
  • "text_preview": "string",
  • "readability": "string",
  • "average_readability": 0,
  • "suggested_word_count_limits": {
    },
  • "country_code": "string",
  • "onpage_audit_country_code": "string",
  • "location": "string",
  • "location_id": 0,
  • "status_code": 0,
  • "hostname": "string",
  • "meta_title": "string",
  • "meta_desc": "string",
  • "hero_image": "http://example.com",
  • "hero_image_alt_text": "string",
  • "score_extended": { },
  • "score_counts": { },
  • "created_by_user": "string",
  • "wp_post_status": "string",
  • "wp_post_type": "string",
  • "wp_synced_at": "2019-08-24T14:15:22Z",
  • "wp_post_categories": [
    ],
  • "wp_post_author_id": 0,
  • "wp_sync_at_date": "2019-08-24",
  • "wp_sync_at_time": "string",
  • "wp_published_at_url": "http://example.com",
  • "permalink": "string",
  • "applied_refiners": [
    ],
  • "should_use_headless_browser": true
}

Partially update a page

Update one or more page fields: title, editor_state, cleaned_html, status, meta_title, meta_desc, hero_image, hero_image_alt_text, language, version, etc.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
title
string
editor_state
string

Draft.js editor state JSON

cleaned_html
string
is_cleaned_html_updated
boolean
status
string
Enum: "draft" "in_progress" "ready_to_publish" "published" "archived"
meta_title
string
meta_desc
string
hero_image
string or null <uri>
hero_image_alt_text
string
language
string
version
string

Required when updating content to prevent concurrent modification

brand_vault_uuid
string or null <uuid>
due_date
string or null <date>
assigned_to_users
Array of strings
feature_image
string or null <uri>
feature_image_alt_text
string or null

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "editor_state": "string",
  • "cleaned_html": "string",
  • "is_cleaned_html_updated": true,
  • "status": "draft",
  • "meta_title": "string",
  • "meta_desc": "string",
  • "hero_image": "http://example.com",
  • "hero_image_alt_text": "string",
  • "language": "string",
  • "version": "string",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "due_date": "2019-08-24",
  • "assigned_to_users": [
    ],
  • "feature_image": "http://example.com",
  • "feature_image_alt_text": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "id": 0,
  • "title": "string",
  • "url": "http://example.com",
  • "status": "draft",
  • "score": 0,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability_grade": "string",
  • "readability_grade_range": "string",
  • "version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "project_id": 0,
  • "project_name": "string",
  • "brand_vault": {
    },
  • "due_date": "2019-08-24",
  • "tags": [
    ],
  • "assigned_to_users": [
    ],
  • "imported_from_url": "http://example.com",
  • "wp_synced": true,
  • "wp_syncing_task_status": "string",
  • "language": "string",
  • "feature_image": "http://example.com",
  • "feature_image_alt_text": "string",
  • "was_deleted": true,
  • "editor_state": "string",
  • "cleaned_html": "string",
  • "is_cleaned_html_updated": true,
  • "text_preview": "string",
  • "readability": "string",
  • "average_readability": 0,
  • "suggested_word_count_limits": {
    },
  • "country_code": "string",
  • "onpage_audit_country_code": "string",
  • "location": "string",
  • "location_id": 0,
  • "status_code": 0,
  • "hostname": "string",
  • "meta_title": "string",
  • "meta_desc": "string",
  • "hero_image": "http://example.com",
  • "hero_image_alt_text": "string",
  • "score_extended": { },
  • "score_counts": { },
  • "created_by_user": "string",
  • "wp_post_status": "string",
  • "wp_post_type": "string",
  • "wp_synced_at": "2019-08-24T14:15:22Z",
  • "wp_post_categories": [
    ],
  • "wp_post_author_id": 0,
  • "wp_sync_at_date": "2019-08-24",
  • "wp_sync_at_time": "string",
  • "wp_published_at_url": "http://example.com",
  • "permalink": "string",
  • "applied_refiners": [
    ],
  • "should_use_headless_browser": true
}

Delete a page

Soft-deletes the page. The page is no longer returned in list results but data is preserved for recovery.

Authorizations:
apiKeyAuth

Responses

Update hero image

Set or clear the hero image and its alt text for a page.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
hero_image
string or null <uri>
hero_image_alt_text
string

Responses

Request samples

Content type
application/json
{}

Set article status via action endpoint

Update article status using action-style endpoints (e.g. draft, published).

Authorizations:
apiKeyAuth
path Parameters
status
required
string
Enum: "draft" "in_progress" "ready_to_publish" "published" "archived"
Request Body schema: application/json
status
string

Responses

Request samples

Content type
application/json
{
  • "status": "string"
}

Content Assistant: Pages - Keywords

Manage target keywords and keyword data for a page

Get compact keywords and focus terms data

Returns a lightweight snapshot of the page's SEO score, focus terms, clustered focus terms, and questions. Used to initialize the editor sidebar.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "score": 0,
  • "focus_terms": [
    ],
  • "focus_terms_clustered": [
    ],
  • "questions": [
    ],
  • "focus_terms_grid_data": { }
}

Get full keywords data

Returns the full keyword scoring data: score, focus terms, clustered terms, questions, competitors, SERP schema, and suggested word-count range.

Authorizations:
apiKeyAuth
query Parameters
should_rescore
boolean
Default: false

Force re-scoring of focus terms

Responses

Response samples

Content type
application/json
{
  • "score": 0,
  • "focus_terms": [
    ],
  • "focus_terms_clustered": [
    ],
  • "clusters": [
    ],
  • "questions": [
    ],
  • "competitors_data": { },
  • "status": { },
  • "focus_terms_grid_data": { },
  • "keyword_suggestions_grid_data": { },
  • "serps_schema": { },
  • "common_citations": { },
  • "target_keywords": [
    ],
  • "suggested_word_count_limits": {
    },
  • "should_repoll": true
}

Add or edit target keyword

Add a new target keyword to the page, or replace an existing one (edited_id). Provide either country_code or location + location_id.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "target_keyword": {
    }
}

Remove target keyword

Remove a target keyword from the page.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "target_keyword": {
    }
}

Get keyword suggestions (v1)

Returns a list of keyword suggestions based on the page title and content.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get keyword suggestions (v2)

Enhanced keyword suggestions with additional scoring signals.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Content Assistant: Pages - Analysis

SEO analysis and page scoring

Get page SEO analysis

Returns on-page SEO analysis, technical issues, and content recommendations.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "technical_score": 0,
  • "content_score": 0,
  • "issues": [
    ],
  • "page_structure": { },
  • "serps_schema": { }
}

Analyze a specific URL for a page

Triggers analysis of the page against a specific live URL.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

Responses

Request samples

Content type
application/json
{}

Re-crawl page URL

Triggers a fresh crawl of the page's associated URL to update its HTML content. Returns 400 if no html_analysis record exists for the page yet.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{ }

Get internal link suggestions (v1)

Returns internal link opportunities for the page based on content analysis.

Authorizations:
apiKeyAuth
query Parameters
should_reprocess
boolean
Default: false

Force reprocessing of suggestions

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Get internal link suggestions (v2)

Enhanced internal link suggestions with additional context signals. Returns 503 if the external link-suggestion service is unavailable.

Authorizations:
apiKeyAuth
query Parameters
should_reprocess
boolean
Default: false

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Dismiss an internal link suggestion

Marks an internal link suggestion as dismissed so it no longer appears in the page's suggestion list. Both the target URL and the anchor keywords are stored to prevent the suggestion from re-appearing.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

URL of the suggested link target to dismiss

keywords
Array of strings

Anchor keyword(s) associated with this suggestion

Responses

Request samples

Content type
application/json
{}

Bookmark an internal link suggestion

Saves an internal link suggestion to the page's bookmarked list so the user can action it later without it being dismissed.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

URL of the suggested link target to bookmark

Responses

Request samples

Content type
application/json
{}

Content Assistant: Pages - Export & Import

Export articles to Google Docs / HTML / CSV; import from URL or spreadsheet

Export article to Google Doc

Creates a new Google Doc with the article's content and returns the doc URL.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{}

Export content brief to Google Doc

Exports the page's content brief (headings, notes) as a Google Doc.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{}

Export article as HTML

Returns the article's cleaned HTML content as a downloadable file (text/html). The response filename is derived from the page title.

Authorizations:
apiKeyAuth

Responses

Export pages to CSV

Generates and returns a CSV export for the specified page UUIDs.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
required
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ]
}

Import content from a live URL

Crawls the given URL and imports its HTML content into the page editor.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>
should_override_content
boolean
Default: true

Whether to overwrite existing content

should_use_headless_browser
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "should_override_content": true,
  • "should_use_headless_browser": false
}

Parse spreadsheet for bulk article creation

Upload a CSV/XLSX file or provide a Google Sheets URL to extract article titles and keywords for bulk creation. Supports Brand Vault association.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
file
string <binary>

CSV or XLSX file

gsheets_url
string <uri>

Google Sheets public URL (alternative to file upload)

brand_vault_uuid
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Content Assistant: Pages - WordPress

WordPress publishing and bulk sync

Publish article to WordPress

Publishes the article to the connected WordPress website. Supports post types, categories, author, permalink, and scheduled publishing.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
wp_website_id
required
integer

WP website heartbeat ID

post_url
string <uri>
post_status
string
Enum: "publish" "draft" "private" "scheduled"
post_type
string
Enum: "post" "page" "custom"
permalink
string
post_categories
Array of strings
post_author
integer
post_parent
integer or null
sync_at_date
string <date>

Schedule publish date (required for scheduled posts)

sync_at_time
string

Schedule publish time (HH:MM or HH:MM:SS, optional tz offset)

force_override
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "wp_website_id": 0,
  • "post_url": "http://example.com",
  • "post_status": "publish",
  • "post_type": "post",
  • "permalink": "string",
  • "post_categories": [
    ],
  • "post_author": 0,
  • "post_parent": 0,
  • "sync_at_date": "2019-08-24",
  • "sync_at_time": "string",
  • "force_override": false
}

Bulk sync articles to WordPress

Sync multiple articles to their associated WordPress websites.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ]
}

Get connected WordPress websites

Returns all WordPress websites connected to the account with heartbeat status.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Content Assistant: Pages - Permissions

Per-page permission and viewer management

Get page sharing permissions

Returns current sharing/access settings for the page.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "is_public": true,
  • "public_share_hash": "string",
  • "shared_with": [
    ]
}

Update page sharing permissions

Update who can access the page and at what permission level.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
is_public
boolean
Array of objects

Responses

Request samples

Content type
application/json
{
  • "is_public": true,
  • "shared_with": [
    ]
}

Response samples

Content type
application/json
{
  • "is_public": true,
  • "public_share_hash": "string",
  • "shared_with": [
    ]
}

Get active viewers for a page

Returns a list of users currently viewing or recently active on this page.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Content Assistant: Focus Terms

Focus term search and per-page exclusion/insertion actions

Query focus terms for a keyword

Returns a set of NLP-derived focus terms, questions, and competitor data for the given query keyword, country, and language.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query
required
string

Target keyword or topic

country
required
string

Country code (e.g. "us")

language
required
string

Language code (e.g. "en")

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "country": "string",
  • "language": "string"
}

Response samples

Content type
application/json
{
  • "score": 0,
  • "focus_terms": [
    ],
  • "questions": [
    ],
  • "competitors": { },
  • "should_repoll": true
}

List saved focus terms

Returns the user's saved focus terms history.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Exclude a focus term from a page

Marks a single focus term as excluded so it no longer counts against the page score.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
focus_term
required
string

Responses

Request samples

Content type
application/json
{
  • "focus_term": "string"
}

Bulk exclude focus terms from a page

Marks multiple focus terms as excluded at once.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
focus_terms
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "focus_terms": [
    ]
}

Add custom focus terms to a page

Adds one or more custom focus terms to track for this page.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
focus_terms
Array of strings

Responses

Request samples

Content type
application/json
{
  • "focus_terms": [
    ]
}

Get term insertion suggestions

Returns suggested sentences where the given focus terms can be naturally inserted.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
focus_terms
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "focus_terms": [
    ]
}

Get link insertion suggestions

Returns suggested anchor positions in the article for the given link targets.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
links
required
Array of strings <uri> [ items <uri > ]

Responses

Request samples

Content type
application/json
{}

Content Assistant: Content Audit

Content audit task creation, retrieval, recrawl, and completion tracking

List content audits

Returns all content audit tasks for the authenticated account.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 10
search
string
ordering
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Create a content audit

Initiates a content audit for the given URL and up to 3 target keywords. Crawls the page and computes content score, technical score, focus terms, and SERP analysis.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

URL to audit

target_keywords
required
Array of strings [ 1 .. 3 ] items

1-3 target keywords

country_code
string

ISO alpha-2 country code

location
string

Named location (overrides country_code)

location_id
integer

Location ID paired with location

should_use_headless_browser
boolean
Default: true

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "http://example.com",
  • "country_code": "string",
  • "location_id": 0,
  • "location": "string",
  • "is_processed": true,
  • "import_failed": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "reprocessed_at": "2019-08-24T14:15:22Z",
  • "public_share_hash": "string",
  • "task_status": "string",
  • "is_completed": true,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability": "string",
  • "readability_grade_range": "string",
  • "should_repoll": true,
  • "is_target_keyword_failed": true,
  • "real_url": "http://example.com",
  • "status_code": 0,
  • "technical_score_color": "string",
  • "content_score_color": "string"
}

Bulk create content audits

Creates multiple content audit tasks from a URL list, Google Sheets URL, or file upload.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
file
string <binary>
gsheets_url
string <uri>

Responses

Get content audit details

Returns the full audit result including technicals, content analysis, focus terms, and internal link suggestions.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "http://example.com",
  • "country_code": "string",
  • "location_id": 0,
  • "location": "string",
  • "is_processed": true,
  • "import_failed": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "reprocessed_at": "2019-08-24T14:15:22Z",
  • "public_share_hash": "string",
  • "task_status": "string",
  • "is_completed": true,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability": "string",
  • "readability_grade_range": "string",
  • "should_repoll": true,
  • "is_target_keyword_failed": true,
  • "real_url": "http://example.com",
  • "status_code": 0,
  • "technical_score_color": "string",
  • "content_score_color": "string",
  • "recommended_backlinks": [
    ],
  • "technicals": { },
  • "content": { },
  • "page_structure": { },
  • "focus_terms": [
    ],
  • "internal_outlink_suggestions": [
    ],
  • "internal_inlink_suggestions": [
    ],
  • "issues": [
    ],
  • "title": "string",
  • "meta_description": "string",
  • "screenshot_image": "http://example.com",
  • "serps_schema": { },
  • "page_health": { },
  • "audit_duration": 0
}

Delete a content audit

Permanently deletes the content audit record and all associated analysis data.

Authorizations:
apiKeyAuth

Responses

Re-crawl content audit

Triggers a fresh crawl and re-analysis of the audit's URL. Returns the updated audit record after initiating reprocessing.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "http://example.com",
  • "country_code": "string",
  • "location_id": 0,
  • "location": "string",
  • "is_processed": true,
  • "import_failed": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "reprocessed_at": "2019-08-24T14:15:22Z",
  • "public_share_hash": "string",
  • "task_status": "string",
  • "is_completed": true,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability": "string",
  • "readability_grade_range": "string",
  • "should_repoll": true,
  • "is_target_keyword_failed": true,
  • "real_url": "http://example.com",
  • "status_code": 0,
  • "technical_score_color": "string",
  • "content_score_color": "string"
}

Update audit completion status

Mark audit tasks or recommendations as complete/incomplete.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
is_completed
boolean

Responses

Request samples

Content type
application/json
{
  • "is_completed": true
}

Dismiss an outlink suggestion from audit

Marks an internal outlink suggestion as dismissed so it no longer appears in the audit's suggestion list.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

URL of the outlink suggestion to dismiss

Responses

Request samples

Content type
application/json
{}

Dismiss an inlink suggestion from audit

Marks an internal inlink (backlink) suggestion as dismissed so it no longer appears in the audit's suggestion list.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

URL of the inlink suggestion to dismiss

Responses

Request samples

Content type
application/json
{}

Export audit report to Google Doc

Creates a Google Doc with the full content audit report.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{}

Content Assistant: Target Keywords

Keyword research and target keyword saved list

List saved target keywords

Returns the user's saved target keyword research history.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Research a target keyword

Initiates SERP research for a given keyword. Returns data asynchronously - poll GET /api/target-keywords/{id}/ for results.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keyword
required
string
country_code
string

ISO alpha-2 country code

location
string
location_id
integer

Responses

Request samples

Content type
application/json
{
  • "keyword": "best hiking boots",
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "keyword": "string",
  • "country_code": "string",
  • "location": "string",
  • "location_id": 0,
  • "sv": 0,
  • "cpc": 0,
  • "competition": 0,
  • "kd": 0,
  • "sv_top_countries": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "is_saved": true
}

Get target keyword detail

Returns full SERP data, competitor metrics, and content recommendations for the keyword.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "keyword": "string",
  • "country_code": "string",
  • "location": "string",
  • "location_id": 0,
  • "sv": 0,
  • "cpc": 0,
  • "competition": 0,
  • "kd": 0,
  • "sv_top_countries": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "is_saved": true,
  • "serp_data": { },
  • "questions": [
    ],
  • "similar_keywords": [
    ],
  • "content_recommendations": { }
}

Save a target keyword to the list

Persists this target keyword to the user's saved research list.

Authorizations:
apiKeyAuth

Responses

Remove a target keyword from the list

Authorizations:
apiKeyAuth

Responses

Create a new page from a target keyword

Creates a blank page, attaches the target keyword to it, and returns the new page object. Consumes 1 article quota unit.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "id": 0,
  • "title": "string",
  • "url": "http://example.com",
  • "status": "draft",
  • "score": 0,
  • "content_score": 0,
  • "technical_score": 0,
  • "word_count": 0,
  • "readability_grade": "string",
  • "readability_grade_range": "string",
  • "version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "project_id": 0,
  • "project_name": "string",
  • "brand_vault": {
    },
  • "due_date": "2019-08-24",
  • "tags": [
    ],
  • "assigned_to_users": [
    ],
  • "imported_from_url": "http://example.com",
  • "wp_synced": true,
  • "wp_syncing_task_status": "string",
  • "language": "string",
  • "feature_image": "http://example.com",
  • "feature_image_alt_text": "string",
  • "was_deleted": true
}

Content Assistant: Projects

Article project (folder) management and AI settings per project

List article projects (folders)

Returns all article projects for the account. Optionally filter by those with topical maps.

Authorizations:
apiKeyAuth
query Parameters
has_topical_map
boolean

Only return projects that have a topical map

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or rename an article project

Create a new project with the given name and domain. If a deleted project with the same name exists it will be restored. Sending id + name renames the project.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 200 characters
description
string
is_active
boolean
Default: true
timezone
string

IANA timezone string (e.g. America/New_York)

object (PlatformsConfig)
default_approval_type
string
Enum: "AUTO_PUBLISH" "APPROVE_IF_IMAGE" "AI_IMAGES_ONLY" "APPROVE_FOR_PUBLISH"
default_image_source_type
string or null
object (AISettings)
image_prompt
string <= 1000 characters

Convenience alias - merged into ai_settings.image_prompt on save

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "string",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update project AI settings

Update AI generation settings (language, tone, content structure) for all articles in the project.

Authorizations:
apiKeyAuth
path Parameters
projectId
required
integer

Project ID (use 0 for uncategorized articles)

Request Body schema: application/json
required
language
string
tone_of_voice
string
point_of_view
string
length
string
Enum: "short" "medium" "long"
use_list
boolean
use_table
boolean
disable_conclusion
boolean
enable_key_takeaways
boolean
table_of_contents
boolean
bold_terms_to_include
boolean
llm
string
images_engine
string
generate_metadata
boolean
generate_hero_image
boolean
generate_images
boolean
company_name
string
website_url
string
niche
string
search_intent
string
reading_level
string
writing_style
string

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "tone_of_voice": "string",
  • "point_of_view": "string",
  • "length": "short",
  • "use_list": true,
  • "use_table": true,
  • "disable_conclusion": true,
  • "enable_key_takeaways": true,
  • "table_of_contents": true,
  • "bold_terms_to_include": true,
  • "llm": "string",
  • "images_engine": "string",
  • "generate_metadata": true,
  • "generate_hero_image": true,
  • "generate_images": true,
  • "company_name": "string",
  • "website_url": "string",
  • "niche": "string",
  • "search_intent": "string",
  • "reading_level": "string",
  • "writing_style": "string"
}

Delete an article project

Soft-deletes the project. Articles in the project become uncategorized.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
id
required
integer

Responses

Request samples

Content type
application/json
{
  • "id": 0
}

Add a page to a project

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
id
required
integer

Project ID

uuid
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Auto-populate project AI settings from domain

Analyzes the domain and auto-fills AI settings (niche, tone, language, etc.) for the project.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string

Domain to analyze (e.g. "example.com")

Responses

Request samples

Content type
application/json
{
  • "domain": "string"
}

Content Assistant: AI Writer

AI content outline, heading suggestions, and first-draft generation (v1/v2)

Get AI content outline (v1)

Returns AI-generated heading suggestions and content outline for the page. Pass should_get_history=true to retrieve previous outline generations. Returns 406 if the page still has the default title and no content_topic is supplied.

Authorizations:
apiKeyAuth
query Parameters
content_topic
string
terms_to_include
string
num_of_results
integer
Default: 1
should_get_history
boolean
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get AI content outline (standalone, no page UUID)

Generates an AI content outline without requiring an existing page. Accepts the same query params as the page-linked variant.

Authorizations:
apiKeyAuth
query Parameters
content_topic
string
terms_to_include
string
num_of_results
integer
Default: 1
should_get_history
boolean
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get AI heading suggestions

Returns AI-generated H1/H2 heading suggestions for the page. Accepts content_topic, number_of_headings (default 6), and optional uuid override query params.

Authorizations:
apiKeyAuth
query Parameters
content_topic
string

Override topic for heading generation

number_of_headings
integer
Default: 6

Responses

Response samples

Content type
application/json
{
  • "h1_suggestions": [
    ],
  • "h2_suggestions": [
    ]
}

Generate a content fragment (rewrite/snippet)

Generates a short content snippet for a keyword. Use type: rewrite_content to rewrite existing content.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keyword
required
string
type
string
Value: "rewrite_content"

Omit for new content generation

Responses

Request samples

Content type
application/json
{
  • "keyword": "string",
  • "type": "rewrite_content"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "keyword": "string",
  • "result": "string",
  • "task_status": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Bulk-create articles from content planner

Creates multiple articles from content planner data with AI-generated content.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "pages": [
    ]
}

Content Assistant: AI Writer v2

First Draft Generator - structured multi-step outline (v2)

Generate First Draft (v2, page-linked)

Generates a structured multi-step AI content outline (First Draft Generator v2) linked to an existing page. Pass should_get_history: true to retrieve history.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
content_topic
string
terms_to_include
Array of strings
num_of_results
integer
length
string
Enum: "short" "medium" "long"
content_type
string
language
string
tone_of_voice
string
point_of_view
string
should_get_history
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "content_topic": "string",
  • "terms_to_include": [
    ],
  • "num_of_results": 0,
  • "length": "short",
  • "content_type": "string",
  • "language": "string",
  • "tone_of_voice": "string",
  • "point_of_view": "string",
  • "should_get_history": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "string",
  • "headings": [
    ]
}

Generate First Draft (v2, standalone)

Generates a first-draft outline without requiring an existing page UUID.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
content_topic
string
terms_to_include
Array of strings
num_of_results
integer
length
string
Enum: "short" "medium" "long"
content_type
string
language
string
tone_of_voice
string
point_of_view
string
should_get_history
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "content_topic": "string",
  • "terms_to_include": [
    ],
  • "num_of_results": 0,
  • "length": "short",
  • "content_type": "string",
  • "language": "string",
  • "tone_of_voice": "string",
  • "point_of_view": "string",
  • "should_get_history": false
}

Content Assistant: AI Templates

AI template configuration, generation history, and execution

Get available AI template types

Returns the list of available AI template types with their input field definitions.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate content from an AI template

Executes an AI template (e.g. blog intro, meta description, product description) with the provided input fields.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
type
required
string

Template type identifier

Array of objects
n
integer
Default: 3

Number of results to generate

is_used_in_cg
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "type": "blog_intro",
  • "inputs": [
    ],
  • "n": 3
}

Response samples

Content type
application/json
[
  • {
    }
]

Get AI template generation history

Returns previous template generation results filtered by template type.

Authorizations:
apiKeyAuth
query Parameters
type
required
string

Template type to filter by

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Content Assistant: AI Images

AI hero/article image generation and replacement

Generate AI image

Generates an AI image using the specified prompt, aspect ratio, and engine. Used for article hero images and inline images.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
prompt
required
string
aspect_ratio
string

E.g. '16:9', '1:1', '4:3'

is_realistic
boolean
Default: false
return_random_choice
boolean
Default: true
images_engine
string

AI engine: 'leonardo', 'midjourney', etc.

is_used_in_cg
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "prompt": "A futuristic running shoe on a mountain trail",
  • "aspect_ratio": "16:9",
  • "is_realistic": true,
  • "return_random_choice": true,
  • "images_engine": "leonardo"
}

Response samples

Content type
application/json
{}

Generate AI hero image for page

Generates and attaches an AI hero image to the page based on page title and keywords.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{}

Replace/regenerate an article image

Regenerates an existing article image using AI.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
image_uuid
string <uuid>
prompt
string

Responses

Request samples

Content type
application/json
{
  • "image_uuid": "81aa1675-ce1e-4227-a1b8-beadb95ef40a",
  • "prompt": "string"
}

Content Assistant: AI Settings

User-level AI language, tone, and style settings

Get user AI settings

Returns the user's default AI generation settings (language, tone, POV, content type).

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "default_language": "string",
  • "tone_of_voice": "string",
  • "type_of_content": "string",
  • "point_of_view": "string"
}

Update user AI settings

Replaces the user's default AI generation settings.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
default_language
string

ISO 639-1 language code (validated)

tone_of_voice
string or null
point_of_view
string or null

Responses

Request samples

Content type
application/json
{
  • "default_language": "string",
  • "tone_of_voice": "string",
  • "point_of_view": "string"
}

Response samples

Content type
application/json
{
  • "default_language": "string",
  • "tone_of_voice": "string",
  • "type_of_content": "string",
  • "point_of_view": "string"
}

Content Assistant: SEO Metadata

Bulk SEO metadata batch processing and AI-generated meta-tag suggestions

List bulk SEO metadata batches

Returns all bulk meta-tag generation batches for the account.

Authorizations:
apiKeyAuth
query Parameters
is_repolling
boolean

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create bulk SEO metadata batch

Upload a CSV file with columns Company Name, Keywords, and Title or Page URL to generate bulk AI meta titles and descriptions.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
company_name
required
string
file
required
string <binary>

CSV file with required columns

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "company_name": "string",
  • "rowcount": 0,
  • "processed_rowcount": 0,
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "processing_ended_at": "2019-08-24T14:15:22Z",
  • "processing_status": "PENDING",
  • "public_share_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get bulk SEO metadata batch details

Returns the processing status and results of a metadata batch.

Authorizations:
apiKeyAuth
query Parameters
is_repolling
boolean
hash
string

Public share hash for anonymous access

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "company_name": "string",
  • "rowcount": 0,
  • "processed_rowcount": 0,
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "processing_ended_at": "2019-08-24T14:15:22Z",
  • "processing_status": "PENDING",
  • "public_share_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Generate AI SEO meta tags

Generates AI-powered meta title and meta description suggestions for a given page title, keywords, and optional company info.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
title
required
string

Page title

keyword
required
string

Comma-separated target keywords

company_name
string or null
webpage
string or null <uri>

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "keyword": "string",
  • "company_name": "string",
  • "webpage": "http://example.com"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "string",
  • "results": [
    ],
  • "public_share_hash": "string"
}

Poll meta tag generation result

Returns the current status and generated meta tags for an async meta-tag generation job.

Authorizations:
apiKeyAuth
query Parameters
is_repolling
boolean
hash
string

Public share hash

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "string",
  • "results": [
    ],
  • "public_share_hash": "string"
}

Content Assistant: Files

Image upload utility

Content Assistant: Brand Vault

Core Brand Vault CRUD - create, retrieve, update, delete, archive, restore, and search Brand Vaults. Each Brand Vault is tied to a customer's hostname and stores business info, AI settings, WordPress config, and content rules.

List active Brand Vaults

Returns all active (non-archived) Brand Vaults for the authenticated customer. Optionally filter by hostname using the hostname query parameter to retrieve a specific Brand Vault without knowing its UUID.

Authorizations:
apiKeyAuth
query Parameters
hostname
string

Filter by exact normalized hostname (e.g. example.com). Returns the matching Brand Vault if found.

page
integer
Default: 1
page_size
integer
Default: 20
ordering
string

Order by field. Prefix with - for descending. Options: name, created_at, updated_at

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Create a Brand Vault

Creates a new Brand Vault for the authenticated customer. The hostname is normalized automatically (www stripped, lowercased). Triggers asynchronous RAG initialization and optional business info autofill on creation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
hostname
required
string <= 200 characters

Domain hostname (will be normalized)

name
string or null <= 255 characters
otto_project_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "hostname": "example.com",
  • "name": "My Brand"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "hostname": "string",
  • "status": "active",
  • "archived_at": "2019-08-24T14:15:22Z",
  • "otto_project_id": 0,
  • "business_info": {
    },
  • "default_ai_settings": {
    },
  • "required_internal_links": [
    ],
  • "optional_internal_links": [
    ],
  • "required_external_links": [
    ],
  • "optional_external_links": [
    ],
  • "global_background": "string",
  • "default_microagent_ids": [
    ],
  • "default_microagents": [
    ],
  • "business_info_task_id": "string",
  • "business_info_task_status": "string",
  • "business_info_started_at": "2019-08-24T14:15:22Z",
  • "business_info_finished_at": "2019-08-24T14:15:22Z",
  • "business_info_task_error_message": "string",
  • "ai_settings_task_id": "string",
  • "ai_settings_task_status": "string",
  • "ai_settings_started_at": "2019-08-24T14:15:22Z",
  • "ai_settings_finished_at": "2019-08-24T14:15:22Z",
  • "ai_settings_task_error_message": "string",
  • "brand_voice_detection_status": "pending",
  • "brand_voice_detection_error_message": "string",
  • "image_count": 0,
  • "rag_ingestion_status": "string",
  • "total_words": 0,
  • "total_pages": 0,
  • "crawl_error_message": "string",
  • "crawl_error_link": "string",
  • "has_notice": true,
  • "notice_message": "string",
  • "wp_website_id": 0,
  • "wp_auto_upload": false,
  • "wp_url_slug": "string",
  • "wp_post_type": "post",
  • "wp_post_status": "draft",
  • "wp_post_categories": [
    ],
  • "public_share_hash": "string",
  • "is_publicly_shared": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Brand Vault detail

Returns full Brand Vault object including business info, AI settings, status, and computed fields.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "hostname": "string",
  • "status": "active",
  • "archived_at": "2019-08-24T14:15:22Z",
  • "otto_project_id": 0,
  • "business_info": {
    },
  • "default_ai_settings": {
    },
  • "required_internal_links": [
    ],
  • "optional_internal_links": [
    ],
  • "required_external_links": [
    ],
  • "optional_external_links": [
    ],
  • "global_background": "string",
  • "default_microagent_ids": [
    ],
  • "default_microagents": [
    ],
  • "business_info_task_id": "string",
  • "business_info_task_status": "string",
  • "business_info_started_at": "2019-08-24T14:15:22Z",
  • "business_info_finished_at": "2019-08-24T14:15:22Z",
  • "business_info_task_error_message": "string",
  • "ai_settings_task_id": "string",
  • "ai_settings_task_status": "string",
  • "ai_settings_started_at": "2019-08-24T14:15:22Z",
  • "ai_settings_finished_at": "2019-08-24T14:15:22Z",
  • "ai_settings_task_error_message": "string",
  • "brand_voice_detection_status": "pending",
  • "brand_voice_detection_error_message": "string",
  • "image_count": 0,
  • "rag_ingestion_status": "string",
  • "total_words": 0,
  • "total_pages": 0,
  • "crawl_error_message": "string",
  • "crawl_error_link": "string",
  • "has_notice": true,
  • "notice_message": "string",
  • "wp_website_id": 0,
  • "wp_auto_upload": false,
  • "wp_url_slug": "string",
  • "wp_post_type": "post",
  • "wp_post_status": "draft",
  • "wp_post_categories": [
    ],
  • "public_share_hash": "string",
  • "is_publicly_shared": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a Brand Vault

Partially updates a Brand Vault. Supports updating name, hostname, and otto_project_id. WordPress integration fields are also accepted.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string or null <= 255 characters
hostname
string <= 200 characters
otto_project_id
integer or null
wp_website_id
integer or null
wp_auto_upload
boolean
wp_url_slug
string or null <= 2000 characters
wp_post_type
string or null
Enum: "post" "page"
wp_post_status
string or null
Enum: "draft" "publish"
wp_post_categories
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "hostname": "string",
  • "otto_project_id": 0,
  • "wp_website_id": 0,
  • "wp_auto_upload": true,
  • "wp_url_slug": "string",
  • "wp_post_type": "post",
  • "wp_post_status": "draft",
  • "wp_post_categories": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "hostname": "string",
  • "status": "active",
  • "archived_at": "2019-08-24T14:15:22Z",
  • "otto_project_id": 0,
  • "business_info": {
    },
  • "default_ai_settings": {
    },
  • "required_internal_links": [
    ],
  • "optional_internal_links": [
    ],
  • "required_external_links": [
    ],
  • "optional_external_links": [
    ],
  • "global_background": "string",
  • "default_microagent_ids": [
    ],
  • "default_microagents": [
    ],
  • "business_info_task_id": "string",
  • "business_info_task_status": "string",
  • "business_info_started_at": "2019-08-24T14:15:22Z",
  • "business_info_finished_at": "2019-08-24T14:15:22Z",
  • "business_info_task_error_message": "string",
  • "ai_settings_task_id": "string",
  • "ai_settings_task_status": "string",
  • "ai_settings_started_at": "2019-08-24T14:15:22Z",
  • "ai_settings_finished_at": "2019-08-24T14:15:22Z",
  • "ai_settings_task_error_message": "string",
  • "brand_voice_detection_status": "pending",
  • "brand_voice_detection_error_message": "string",
  • "image_count": 0,
  • "rag_ingestion_status": "string",
  • "total_words": 0,
  • "total_pages": 0,
  • "crawl_error_message": "string",
  • "crawl_error_link": "string",
  • "has_notice": true,
  • "notice_message": "string",
  • "wp_website_id": 0,
  • "wp_auto_upload": false,
  • "wp_url_slug": "string",
  • "wp_post_type": "post",
  • "wp_post_status": "draft",
  • "wp_post_categories": [
    ],
  • "public_share_hash": "string",
  • "is_publicly_shared": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a Brand Vault

Permanently deletes a Brand Vault and all associated data.

Authorizations:
apiKeyAuth

Responses

Get Brand Vault overview metrics

Returns aggregated metrics for the Brand Vault dashboard: word counts, page counts, image/video counts (breakdown by source), and source processing status counts.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "total_words": 0,
  • "total_pages": 0,
  • "total_images": 0,
  • "total_videos": 0,
  • "images_breakdown": {
    },
  • "videos_breakdown": {
    },
  • "total_sources": 0,
  • "processed_count": 0,
  • "processing_count": 0,
  • "failed_count": 0,
  • "last_processed_at": "2019-08-24T14:15:22Z"
}

List all Brand Vault content sources

Returns all RAG content sources associated with this Brand Vault - domain crawls, uploaded files, and URL sources. Used to populate the Sources tab.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get source detail

Returns detailed metadata for a single Brand Vault content source.

Authorizations:
apiKeyAuth
path Parameters
sourceId
required
string

Source UUID (from BrandVaultSource.uuid)

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "source_id": "string",
  • "source_type": "string",
  • "source_type_display_name": "string",
  • "name": "string",
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_by": "string",
  • "metadata": { }
}

Delete a content source

Removes a content source from the Brand Vault and deletes its indexed data from the RAG store.

Authorizations:
apiKeyAuth
path Parameters
sourceId
required
string

Responses

Get business information

Returns the structured business information stored on this Brand Vault.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "business_name": "string",
  • "website": "string",
  • "description": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "street_address": "string",
  • "city": "string",
  • "state": "string",
  • "postal_code": "string",
  • "country": "string",
  • "business_address": "string",
  • "language_code": "string",
  • "number_of_employees": 0,
  • "vat_id": "string",
  • "tax_id": "string",
  • "iso_6523_code": "string",
  • "serp_location_text": "string",
  • "uvp": "string",
  • "brand_identity": "string",
  • "business_model_description": "string",
  • "extracted_from": "string"
}

Update business information

Partially updates the business information for the Brand Vault. Supports all business info fields including address components, tax IDs, UVP, and brand identity.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
business_name
string or null <= 500 characters

Official business/company name

website
string or null <= 500 characters

Primary website URL

description
string or null <= 20000 characters

Business description (max 3000 words)

email
string or null <email>
phone
string or null <= 50 characters
street_address
string or null <= 300 characters
city
string or null <= 100 characters
state
string or null <= 100 characters
postal_code
string or null <= 20 characters
country
string or null <= 100 characters
language_code
string or null <= 10 characters

Primary business language (ISO 639-1)

number_of_employees
integer or null >= 0
vat_id
string or null <= 50 characters
tax_id
string or null <= 50 characters
iso_6523_code
string or null <= 50 characters

ISO 6523 ICD code (format: XXXX:XXXXXXXXX)

serp_location_text
string or null <= 200 characters

Location for SERP/competitor tracking

uvp
string or null

Unique Value Proposition (max 80 words)

brand_identity
string or null

Brand personality, tone, and style (max 80 words)

business_model_description
string or null

How the business generates revenue (max 80 words)

Responses

Request samples

Content type
application/json
{
  • "business_name": "Acme Corp",
  • "description": "We build great products.",
  • "email": "contact@acme.com",
  • "phone": "+1-555-0100"
}

Response samples

Content type
application/json
{
  • "business_name": "string",
  • "website": "string",
  • "description": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "street_address": "string",
  • "city": "string",
  • "state": "string",
  • "postal_code": "string",
  • "country": "string",
  • "business_address": "string",
  • "language_code": "string",
  • "number_of_employees": 0,
  • "vat_id": "string",
  • "tax_id": "string",
  • "iso_6523_code": "string",
  • "serp_location_text": "string",
  • "uvp": "string",
  • "brand_identity": "string",
  • "business_model_description": "string",
  • "extracted_from": "string"
}

Auto-fill business info from website

Triggers an asynchronous AI task that crawls the Brand Vault's domain and extracts structured business information. Returns a task_id that can be polled via GET /api/core/v1/task-results/{taskId} to get the result.

Authorizations:
apiKeyAuth
Request Body schema: application/json
optional
website
string <= 500 characters

Optional override URL to extract info from (defaults to Brand Vault hostname)

Responses

Request samples

Content type
application/json
{
  • "website": "string"
}

Response samples

Content type
application/json
{
  • "task_id": "string"
}

Get content/AI settings

Returns the AI content settings and link rules stored on this Brand Vault.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "brand_vault_id": 0,
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "required_internal_links": [
    ],
  • "optional_internal_links": [
    ],
  • "required_external_links": [
    ],
  • "optional_external_links": [
    ],
  • "global_background": "string",
  • "default_microagent_ids": [
    ],
  • "wp_website_id": 0,
  • "wp_post_status": "string",
  • "wp_post_type": "string",
  • "wp_post_categories": [
    ],
  • "wp_auto_upload": true,
  • "wp_url_slug": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update content/AI settings

Updates the Content tab settings for a Brand Vault. Accepts a flat payload where known model fields (link settings, WordPress config, global background, default microagents) are routed to their columns and any remaining fields are merged into the default_ai_settings JSON field.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
Array of objects (LinkSetting)
Array of objects (LinkSetting)
Array of objects (LinkSetting)
Array of objects (LinkSetting)
global_background
string or null
default_microagent_ids
Array of integers
wp_website_id
integer or null
wp_post_status
string or null
Enum: "draft" "publish"
wp_post_type
string or null
Enum: "post" "page"
wp_post_categories
Array of strings
wp_auto_upload
boolean or null
wp_url_slug
string or null <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "required_internal_links": [
    ],
  • "optional_internal_links": [
    ],
  • "required_external_links": [
    ],
  • "optional_external_links": [
    ],
  • "global_background": "string",
  • "default_microagent_ids": [
    ],
  • "wp_website_id": 0,
  • "wp_post_status": "draft",
  • "wp_post_type": "post",
  • "wp_post_categories": [
    ],
  • "wp_auto_upload": true,
  • "wp_url_slug": "string"
}

Response samples

Content type
application/json
{
  • "brand_vault_id": 0,
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "required_internal_links": [
    ],
  • "optional_internal_links": [
    ],
  • "required_external_links": [
    ],
  • "optional_external_links": [
    ],
  • "global_background": "string",
  • "default_microagent_ids": [
    ],
  • "wp_website_id": 0,
  • "wp_post_status": "string",
  • "wp_post_type": "string",
  • "wp_post_categories": [
    ],
  • "wp_auto_upload": true,
  • "wp_url_slug": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get configuration completion status

Returns per-section completion flags for the Brand Vault setup wizard: business_info, brand_voice, locations, content_rules, knowledge_graph, style_guide. Also returns overall completion_percentage.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "configuration_status": {
    },
  • "completion_percentage": 0
}

Get Brand Vault notices

Returns active (non-dismissed) notices for this Brand Vault such as crawl errors or setup warnings.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Brand Vault processing status

Returns the processing status, progress, and any errors for the Brand Vault initialization pipeline.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "string",
  • "progress": { },
  • "errors": [
    ],
  • "started_at": "2019-08-24T14:15:22Z",
  • "estimated_completion": "2019-08-24T14:15:22Z"
}

Get upload limits and current usage

Returns upload limits (file types, sizes, batch limits), tier-based quotas (max sources, max storage), and current usage counts. Used by the frontend to enforce limits and display storage warnings.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "allowed_file_extensions": [
    ],
  • "allowed_mime_types": {
    },
  • "max_file_size_mb": 0,
  • "max_word_count_per_file": 0,
  • "max_files_per_batch": 0,
  • "tier": "free",
  • "max_sources": 0,
  • "max_total_size_gb": 0,
  • "max_pages_per_domain": 0,
  • "sources_used": 0,
  • "total_size_bytes_used": 0,
  • "total_words_used": 0,
  • "sources_remaining": 0,
  • "size_remaining_bytes": 0,
  • "brand_vault_storage": {
    }
}

Archive a Brand Vault

Moves the Brand Vault to archived state. Archived vaults are retained for 30 days before permanent deletion. Can be restored within that window.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "string",
  • "archived_at": "2019-08-24T14:15:22Z",
  • "permanent_deletion_at": "2019-08-24T14:15:22Z",
  • "message": "string"
}

Restore an archived Brand Vault

Moves the Brand Vault from archived state back to active.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "string",
  • "message": "string"
}

List archived Brand Vaults

Returns archived Brand Vaults for the authenticated customer, including days_left before permanent deletion.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search/autocomplete Brand Vaults

Autocomplete search across Brand Vault names and domains. Returns lightweight result objects with match metadata.

Authorizations:
apiKeyAuth
query Parameters
q
required
string

Search query string

limit
integer
Default: 10

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bulk archive Brand Vaults

Archives multiple Brand Vaults in a single request. Returns count and IDs of archived vaults.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "archived_count": 0,
  • "archived_ids": [
    ]
}

Get filter options for Brand Vault list

Returns available filter options (status counts, location availability) for the Brand Vault list view.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "statuses": [
    ],
  • "locations": {
    }
}

Generate AI settings from business context

Uses AI to generate default_ai_settings for a Brand Vault based on the business info and domain content. This is the "Brand Vault AI" autofill for the Content tab.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
brand_vault_uuid
required
string <uuid>

UUID of the Brand Vault to generate settings for

Responses

Request samples

Content type
application/json
{
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc"
}

Response samples

Content type
application/json
{
  • "task_id": "string"
}

Content Assistant: Brand Vault Images

Image management within a Brand Vault - upload, list, update alt text, tag, bulk operations, and AI-powered alt text regeneration.

List Brand Vault images

Returns all images uploaded to this Brand Vault. Optionally filter by image_type.

Authorizations:
apiKeyAuth
query Parameters
image_type
string
Enum: "logo" "favicon" "image"

Filter by image type: logo, favicon, or image

page
integer
Default: 1
page_size
integer
Default: 20

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Upload a single image

Uploads a single image to the Brand Vault. Maximum 10 MB per image. Triggers asynchronous AI alt text generation after upload. Consumes storage quota.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
image
required
string <binary>

Image file (max 10 MB)

image_type
string
Default: "image"
Enum: "image" "logo" "favicon"
use_for_content_genius
boolean
Default: true

Whether this image should be used in AI content generation

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "image_url": "http://example.com",
  • "image_type": "image",
  • "alt_text": "string",
  • "alt_text_generation_status": "string",
  • "alt_text_generated_at": "2019-08-24T14:15:22Z",
  • "alt_text_generation_error": "string",
  • "use_for_content_genius": true,
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get image detail

Returns metadata for a single Brand Vault image including alt text generation status.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "image_url": "http://example.com",
  • "image_type": "image",
  • "alt_text": "string",
  • "alt_text_generation_status": "string",
  • "alt_text_generated_at": "2019-08-24T14:15:22Z",
  • "alt_text_generation_error": "string",
  • "use_for_content_genius": true,
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update image metadata

Updates the alt_text and/or use_for_content_genius flag on a Brand Vault image.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
alt_text
string <= 1000 characters

Alt text for the image (max 1000 chars)

use_for_content_genius
boolean

Responses

Request samples

Content type
application/json
{
  • "alt_text": "string",
  • "use_for_content_genius": true
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "image_url": "http://example.com",
  • "image_type": "image",
  • "alt_text": "string",
  • "alt_text_generation_status": "string",
  • "alt_text_generated_at": "2019-08-24T14:15:22Z",
  • "alt_text_generation_error": "string",
  • "use_for_content_genius": true,
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an image

Permanently deletes an image from the Brand Vault and frees storage quota.

Authorizations:
apiKeyAuth

Responses

Regenerate alt text for one image

Queues an AI task to regenerate the alt text for a single image. Returns the image with updated alt_text_generation_status.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "image_url": "http://example.com",
  • "image_type": "image",
  • "alt_text": "string",
  • "alt_text_generation_status": "string",
  • "alt_text_generated_at": "2019-08-24T14:15:22Z",
  • "alt_text_generation_error": "string",
  • "use_for_content_genius": true,
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace all tags on an image

Replaces the full tag list on an image. Tags are normalized (lowercased, trimmed, deduplicated).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
tags
required
Array of strings[ items <= 50 characters ]

Tags to set (normalized to lowercase)

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "image_url": "http://example.com",
  • "image_type": "image",
  • "alt_text": "string",
  • "alt_text_generation_status": "string",
  • "alt_text_generated_at": "2019-08-24T14:15:22Z",
  • "alt_text_generation_error": "string",
  • "use_for_content_genius": true,
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Bulk upload images (max 100)

Uploads up to 100 images in a single request. Processing is dispatched asynchronously via Celery. Returns a task ID for progress polling.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
images
required
Array of strings <binary> [ 1 .. 100 ] items [ items <binary > ]

List of image files (max 10 MB each)

image_type
string
Default: "image"
Enum: "image" "logo" "favicon"
use_for_content_genius
boolean
Default: true

Responses

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "queued_count": 0
}

Bulk delete images (max 100)

Permanently deletes up to 100 images in a single request.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

List of image UUIDs (max 100)

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ]
}

Response samples

Content type
application/json
{
  • "deleted_count": 0
}

Bulk regenerate alt text (max 100)

Queues AI alt text regeneration for up to 100 images simultaneously.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

List of image UUIDs (max 100)

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ]
}

Response samples

Content type
application/json
{
  • "queued_count": 0
}

Add tags to multiple images

Adds one or more tags to up to 100 images. Existing tags are preserved (merge, not replace).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]
tags
required
Array of strings[ items <= 50 characters ]

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "updated_count": 0
}

Content Assistant: Brand Vault Locations

Physical location/address management for a Brand Vault. Supports GBP-compatible address fields including business hours, service areas, and booking links.

List Brand Vault locations

Returns all physical locations/addresses stored on this Brand Vault. Includes full GBP-compatible address fields.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "addresses": [
    ]
}

Add a location

Adds a new location/address to the Brand Vault.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuid
string or null

Auto-generated if not provided

street_address
string or null <= 1000 characters
address_locality
string or null <= 200 characters

City

address_administrative_area
string or null <= 200 characters

State/Province

address_country
string or null <= 50 characters

Country code (e.g. US)

address_region
string or null <= 200 characters
postal_code
string or null <= 200 characters
timezone
string or null
lat
number or null <float>
long
number or null <float>
embedded_google_map
string or null <= 2000 characters
is_primary
boolean
Default: false
location_id
integer or null

SERP location ID

location_name
string or null <= 500 characters

SERP location name

gbp_location_id
integer or null

GBP Location ID for sync

object or null
object or null (OpenHours)
Array of objects or null (SpecialHour)
object or null (ServiceArea)
booking_link
string or null <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "street_address": "123 Main St",
  • "address_locality": "San Francisco",
  • "address_administrative_area": "CA",
  • "address_country": "US",
  • "postal_code": "94105",
  • "is_primary": true
}

Response samples

Content type
application/json
{
  • "addresses": [
    ]
}

Update a location

Partially updates a specific location by UUID.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuid
string or null

Auto-generated if not provided

street_address
string or null <= 1000 characters
address_locality
string or null <= 200 characters

City

address_administrative_area
string or null <= 200 characters

State/Province

address_country
string or null <= 50 characters

Country code (e.g. US)

address_region
string or null <= 200 characters
postal_code
string or null <= 200 characters
timezone
string or null
lat
number or null <float>
long
number or null <float>
embedded_google_map
string or null <= 2000 characters
is_primary
boolean
Default: false
location_id
integer or null

SERP location ID

location_name
string or null <= 500 characters

SERP location name

gbp_location_id
integer or null

GBP Location ID for sync

object or null
object or null (OpenHours)
Array of objects or null (SpecialHour)
object or null (ServiceArea)
booking_link
string or null <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "uuid": "string",
  • "street_address": "string",
  • "address_locality": "string",
  • "address_administrative_area": "string",
  • "address_country": "string",
  • "address_region": "string",
  • "postal_code": "string",
  • "timezone": "string",
  • "lat": 0.1,
  • "long": 0.1,
  • "embedded_google_map": "string",
  • "is_primary": false,
  • "location_id": 0,
  • "location_name": "string",
  • "gbp_location_id": 0,
  • "opening_date": {
    },
  • "open_hours": {
    },
  • "special_hours": [
    ],
  • "service_area": {
    },
  • "booking_link": "string"
}

Response samples

Content type
application/json
{
  • "addresses": [
    ]
}

Delete a location

Removes a specific location from the Brand Vault.

Authorizations:
apiKeyAuth

Responses

Set primary location

Marks the specified location as the primary address, un-marking any previous primary.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "addresses": [
    ]
}

Content Assistant: Brand Vault Voice

Brand voice profile management - template selection, custom voice creation (freeform or guided), auto-generation from domain content, voice preview generation, and selection/deselection.

List voice profile templates

Returns all active preset Brand Voice templates available for selection. Templates have canonical names: Professional & Credible, Friendly & Conversational, Bold & Energetic, Creative & Expressive, Luxury & Sophisticated, Educational & Informative.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List voice profiles for a Brand Vault

Returns all voice profiles (both template-based and custom) associated with this Brand Vault, including which one is currently selected.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate voice preview

Generates 4 short preview text samples for a voice profile in different contexts (blog, product, cta, support). Used before selecting or saving a voice.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 200 characters
type
required
string

Voice type/category

language
required
string

Language code

tagline
string or null <= 200 characters
tone_summary
string or null
Array of objects (WritingStyleTrait)
reading_level
string or null
example_sentence
string or null
target_audience
string or null
key_guidelines
string or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "string",
  • "language": "string",
  • "tagline": "string",
  • "tone_summary": "string",
  • "writing_style_traits": [
    ],
  • "reading_level": "string",
  • "example_sentence": "string",
  • "target_audience": "string",
  • "key_guidelines": "string"
}

Response samples

Content type
application/json
{
  • "previews": [
    ]
}

Select a voice profile

Sets the specified voice template or custom voice as the active selected voice for this Brand Vault.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
voice_uuid
required
string <uuid>

UUID of the BrandVoiceTemplate or custom BrandVoice to select

Responses

Request samples

Content type
application/json
{
  • "voice_uuid": "31573483-930c-4a3a-a292-81ca0a455b2f"
}

Deselect the current voice profile

Clears the active voice selection for this Brand Vault.

Authorizations:
apiKeyAuth

Responses

Auto-generate voice from domain content

Uses AI to detect and generate a brand voice profile by analyzing the Brand Vault's domain content. Returns a structured voice profile object with traits, reading level, and example sentence. Does not automatically select the voice.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "type": "string",
  • "language": "string",
  • "tagline": "string",
  • "tone_summary": "string",
  • "reading_level": "string",
  • "example_sentence": "string",
  • "target_audience": "string",
  • "key_guidelines": "string",
  • "writing_style_traits": [
    ]
}

Create a custom voice (freeform)

Creates a custom brand voice profile from unstructured natural language instructions. The backend uses an LLM to parse voice_instructions into structured fields (traits, reading level, tone summary, etc.).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 200 characters
voice_instructions
required
string <= 2500 characters

Unstructured voice description - the LLM parses this into structured fields

auto_select
boolean
Default: true

Automatically select this voice after creation

Responses

Request samples

Content type
application/json
{
  • "name": "My Brand Voice",
  • "voice_instructions": "Friendly and professional tone, approachable language, avoid jargon",
  • "auto_select": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "tagline": "string",
  • "source": "string",
  • "tone_summary": "string",
  • "writing_style_traits": [
    ],
  • "reading_level": "string",
  • "example_sentence": "string",
  • "language_preference": "string",
  • "key_guidelines": "string",
  • "target_audience": "string",
  • "is_selected": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Create a custom voice (guided/structured)

Creates a custom brand voice profile from a structured set of fields rather than free-form text. Ideal for precise voice definition without AI parsing.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 200 characters
tagline
string or null <= 200 characters
tone_summary
string or null
Array of objects (WritingStyleTrait)
reading_level
string or null <= 50 characters
example_sentence
string or null
language_preference
string or null <= 50 characters
key_guidelines
string or null
target_audience
string or null
auto_select
boolean
Default: true
voice_instructions
string or null <= 2500 characters

Optional original freeform instructions for reference

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tagline": "string",
  • "tone_summary": "string",
  • "writing_style_traits": [
    ],
  • "reading_level": "string",
  • "example_sentence": "string",
  • "language_preference": "string",
  • "key_guidelines": "string",
  • "target_audience": "string",
  • "auto_select": true,
  • "voice_instructions": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "tagline": "string",
  • "source": "string",
  • "tone_summary": "string",
  • "writing_style_traits": [
    ],
  • "reading_level": "string",
  • "example_sentence": "string",
  • "language_preference": "string",
  • "key_guidelines": "string",
  • "target_audience": "string",
  • "is_selected": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Re-parse custom voice instructions

Re-runs LLM parsing on updated voice instructions for an existing custom voice. Replaces the structured fields with the new parsing result.

Authorizations:
apiKeyAuth
path Parameters
voiceUuid
required
string <uuid>

UUID of the custom voice to re-parse

Request Body schema: application/json
required
voice_instructions
required
string <= 2500 characters

Updated voice instructions for re-parsing

Responses

Request samples

Content type
application/json
{
  • "voice_instructions": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "tagline": "string",
  • "source": "string",
  • "tone_summary": "string",
  • "writing_style_traits": [
    ],
  • "reading_level": "string",
  • "example_sentence": "string",
  • "language_preference": "string",
  • "key_guidelines": "string",
  • "target_audience": "string",
  • "is_selected": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Content Assistant: Brand Vault Knowledge Graph

Knowledge graph settings for a Brand Vault - authorship, social media profiles, and top pages used to build structured entity data for SEO.

Get knowledge graph settings

Returns authorship, social media profile URLs, and top pages for this Brand Vault's knowledge graph.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{}

Update knowledge graph settings

Partially updates authorship, social profiles, and/or top pages. Supports adding/updating top pages (with UUID for existing, without UUID for new) and deleting pages via delete_top_page_uuids.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
object (Authorship)
object (SocialProfiles)

Social media profile URLs (all 22 platforms)

Array of objects (TopPage)
delete_top_page_uuids
Array of strings

UUIDs of top pages to delete

Responses

Request samples

Content type
application/json
{
  • "authorship": {
    },
  • "social_profiles": {
    },
  • "top_pages": [
    ],
  • "delete_top_page_uuids": [
    ]
}

Response samples

Content type
application/json
{}

Content Assistant: RAG

Retrieval-Augmented Generation - upload source documents, replace uploads, and query Brand Vault knowledge for AI content generation.

Upload source documents to Brand Vault

Uploads one or more documents (PDF, DOCX, TXT, HTML, etc.) to a Brand Vault for RAG ingestion. Files are stored in GCS, processed asynchronously, and indexed for AI retrieval. Maximum 10 files per batch and 10 MB per file.

Returns upload IDs that can be used to track processing status or replace files.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> [ 1 .. 10 ] items [ items <binary > ]

Files to upload (max 10 per batch, max 10 MB each)

brand_vault_uuid
required
string <= 255 characters

UUID of the target Brand Vault

Responses

Response samples

Content type
application/json
{
  • "upload_ids": [
    ],
  • "status": "string",
  • "message": "string",
  • "duplicates": [
    ],
  • "task": { },
  • "replaced_upload_id": "28af72bc-af91-4210-82aa-42213019fa93"
}

Replace an uploaded source file

Replaces the content of an existing upload with a new file. The upload ID is preserved. The new file is re-processed and re-indexed. Useful for updating a document without re-adding it.

Authorizations:
apiKeyAuth
path Parameters
uploadId
required
string <uuid>

UUID of the upload to replace

Request Body schema: multipart/form-data
required
file
required
string <binary>

Replacement file

Responses

Response samples

Content type
application/json
{
  • "upload_ids": [
    ],
  • "status": "string",
  • "message": "string",
  • "duplicates": [
    ],
  • "task": { },
  • "replaced_upload_id": "28af72bc-af91-4210-82aa-42213019fa93"
}

Query Brand Vault knowledge

Queries the RAG index for a Brand Vault using natural language. Optionally uses an LLM to generate a synthesized answer from retrieved chunks. Supports conversation history for multi-turn interactions.

The brand_vault_uuid must belong to the authenticated customer.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query
required
string <= 2000 characters

Natural language query

brand_vault_uuid
required
string

Brand Vault UUID to query

k
integer [ 1 .. 20 ]
Default: 5

Number of results to return

use_llm
boolean
Default: true

Whether to use LLM for answer synthesis

Array of objects or null (ConversationMessage)

Prior conversation messages for multi-turn context

Responses

Request samples

Content type
application/json
{
  • "query": "What are our core product features?",
  • "brand_vault_uuid": "550e8400-e29b-41d4-a716-446655440000",
  • "k": 5,
  • "use_llm": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "query": "string",
  • "original_query": "string",
  • "rewritten_query": "string",
  • "answer": "string",
  • "sources": [
    ],
  • "chunk_id": "string",
  • "response_time_ms": 0.1,
  • "error": "string"
}

Content Assistant: CGenius Content Generation

AI-powered multi-stage content generation pipeline. Each piece of content progresses through stages: Information Retrieval → Headings Outline → Content Brief & Citations → HTML Content Generation. Stages can be triggered individually or all at once.

Create a CGenius content record

Creates a new CGenius content workflow record tied to a content topic. Optionally links to an existing page or a BrandVault for AI settings. This is the initialisation step - generation stages are triggered separately.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
content_topic
required
string

The article topic or title to generate content for

type
required
string

Content type (e.g. "article", "blog_post", "landing_page")

page
integer or null

Optional existing page ID to attach generation to

brand_vault_uuid
string or null <uuid>

BrandVault UUID for AI style and voice settings (mutually exclusive with project)

project_id
integer or null

Project ID for AI settings context (mutually exclusive with brand_vault_uuid)

required
object (CGeniusSettingsContext)
object

Microagent ID → payload dict. Microagents run after HTML generation.

Responses

Request samples

Content type
application/json
{
  • "content_topic": "How to optimise landing pages for conversions",
  • "type": "article",
  • "settings_context": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Get a CGenius content record

Returns full CGenius content record including all stage statuses, settings context, and generated data references.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Update a CGenius content record

Partially update fields on a CGenius content record (e.g. re-assign microagents or update settings).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
object (CGeniusSettingsContext)
microagents
Array of integers

List of microagent IDs to associate

Responses

Request samples

Content type
application/json
{
  • "settings_context": {
    },
  • "microagents": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Poll overall processing status

Returns a lightweight summary of all pipeline stage statuses (information_retrieval, headings_outline, content_brief, html_content, microagents). Use for polling without fetching the full content payload.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "information_retrieval_task_status": "PENDING",
  • "headings_outline_task_status": "PENDING",
  • "content_brief_task_status": "PENDING",
  • "html_content_task_status": "PENDING",
  • "microagents_task_status": "PENDING",
  • "image_generation_task_status": "PENDING",
  • "fully_complete": true
}

Subscribe to SSE generation events

Server-Sent Events stream for real-time generation progress. Each event carries a JSON payload with stage, status, and optional data. The stream ends with a done event when all stages complete.

Content-Type: text/event-stream

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string <uuid>

CGenius content UUID

Responses

Start Stage 1 - Information Retrieval

Triggers async retrieval of SERP data, competitor content, and research sources for the content topic. Sets information_retrieval_task_status to PENDING.

Authorizations:
apiKeyAuth
Request Body schema: application/json
keywords
Array of strings

Optional override keywords for retrieval

search_terms
Array of strings

Responses

Request samples

Content type
application/json
{
  • "keywords": [
    ],
  • "search_terms": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Start Stage 2 - Headings Outline

Triggers AI generation of the article headings/outline from information retrieval data. Requires Stage 1 (information retrieval) to be complete. Returns 400 if prerequisites are not met; 202 if already running.

Authorizations:
apiKeyAuth
Request Body schema: application/json
object

No body fields required for this stage trigger

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "processing"
}

Start Stage 3 - Content Brief and Citations

Triggers AI generation of the content brief (writing instructions, target audience, tone) and citation gathering from the information retrieval data. Requires Stages 1 and 2 (information retrieval + headings outline) to be complete. Returns 400 if prerequisites are not met; 202 if already running.

Authorizations:
apiKeyAuth
Request Body schema: application/json
object

No body fields required for this stage trigger

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "processing"
}

Start Stage 4 - HTML Content Generation

Triggers the full HTML article generation from the approved headings outline and content brief. This is the most compute-intensive stage. On completion, was_published_to_editor is set to true and the page is updated. Requires Stage 3 (content brief) to be complete. Returns 400 if prerequisites are not met; 202 if already running.

Authorizations:
apiKeyAuth
Request Body schema: application/json
user_prompt
string
Default: ""

Optional user instructions to guide HTML generation style or focus

object

Map of microagent IDs to apply during generation (key = microagent ID, value = config object)

Responses

Request samples

Content type
application/json
{
  • "user_prompt": "",
  • "microagents": { }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "processing"
}

Start all stages - full pipeline (single content)

Convenience endpoint that triggers all four generation stages sequentially for a single CGenius content record. Equivalent to calling each stage endpoint in sequence.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
id
required
integer

CGenius content ID

Responses

Request samples

Content type
application/json
{
  • "id": 0
}

Bulk create and start full generation

Creates up to 50 CGenius content records and immediately starts the full generation pipeline for each. Use for batch article creation from content plans or topical maps.

The settings_context (language, length, generate_images) applies to all items unless overridden per-item. Either project_id or brand_vault_uuid must be supplied (not both) to provide AI style settings.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
Array of objects [ 1 .. 50 ] items
required
object (CGeniusSettingsContext)
object

Global microagent payload dict applied to all content items

project_id
integer or null

Global project for all content (mutually exclusive with brand_vault_uuid)

brand_vault_uuid
string or null <uuid>

Global BrandVault for all content (mutually exclusive with project_id)

has_multiple_projects
boolean
Default: false

Set true when each content entry carries its own project_id

Responses

Request samples

Content type
application/json
{
  • "contents": [
    ],
  • "settings_context": {
    },
  • "project_id": 123
}

Response samples

Content type
application/json
{
  • "created_count": 0,
  • "ids": [
    ]
}

Get Stage 1 data - Information Retrieval

Returns the raw information retrieval result (SERP data, competitor analysis, entities).

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "information_retrieval": { },
  • "keywords": [
    ],
  • "search_terms": [
    ]
}

Get Stage 2 data - Headings Outline

Returns the generated headings outline with H2/H3 structure and descriptions.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "headings_outline": { },
  • "headings_outline_raw": { }
}

Get Stage 3 data - Content Brief

Returns the AI-generated content brief (writing instructions, tone, audience, key points).

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "content_brief": { }
}

Get citations data

Returns gathered citation URLs and source metadata.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "citations": { }
}

Get Stage 4 data - HTML Content

Returns the generated HTML article content and word count.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "html_content": "string",
  • "word_count": 0
}

Update headings outline

Allows the user to edit the AI-generated headings outline before proceeding to content brief generation. Updated outline is used for subsequent stages.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
headings_outline
object

Updated headings outline structure

Responses

Request samples

Content type
application/json
{
  • "headings_outline": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Update content brief

Allows the user to edit the AI-generated content brief before HTML generation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
content_brief
object

Updated content brief object

Responses

Request samples

Content type
application/json
{
  • "content_brief": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Update keywords and search terms for information retrieval

Updates the keyword list and search terms used for information retrieval. Useful when the user wants to adjust the research scope before re-running retrieval.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keywords
Array of strings

Primary target keywords

search_terms
Array of strings

Additional search terms to inform content research

Responses

Request samples

Content type
application/json
{
  • "keywords": [
    ],
  • "search_terms": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Get CGenius generation history

Returns a paginated list of all CGenius content records for the authenticated user's account.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 20
search
string

Search by content_topic

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Content Assistant: Microagents

Micro-level AI agents that perform specialized content tasks (e.g. rewriting sections, generating tables, applying brand voice). Can be run on CGenius content or on existing pages.

List available microagents

Returns all microagents available to the authenticated user. Microagents are specialized AI agents that perform focused content tasks (e.g. "Generate Table Section", "Expand Paragraph", "Apply Brand Voice").

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Execute a microagent (sync or async)

Runs a single microagent against provided content payload. For lightweight agents a synchronous result is returned. For heavy agents the task is queued and a task_id is returned for polling.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
microagent_id
required
integer
required
object

Dynamic fields defined by the microagent's prompt variables. Common fields include text_before, text_after, content.

Responses

Request samples

Content type
application/json
{
  • "microagent_id": 5,
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "result": "string"
}

Poll async microagent task status

Check the result of an async microagent execution by task ID.

Authorizations:
apiKeyAuth
query Parameters
task_id
required
string

Task ID returned from execute endpoint

Responses

Response samples

Content type
application/json
{
  • "task_status": "PENDING",
  • "result": "string",
  • "error": "string"
}

Get microagent results for a page

Returns all previous microagent execution results associated with a page.

Authorizations:
apiKeyAuth
query Parameters
page_uuid
string <uuid>

Page UUID to retrieve microagent results for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Run microagents on CGenius HTML content

Applies one or more microagents to the generated HTML content of a CGenius record. Results are merged back into the HTML. Sets microagents_task_status to PENDING.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
object

Microagent ID → payload dict for the microagents to run

Responses

Request samples

Content type
application/json
{
  • "microagents": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Poll microagents stage status

Returns the current status of the microagents processing stage for a CGenius content record.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string"
}

Run microagents on a page

Applies microagents directly to a content page (not via CGenius). Used when the user wants post-generation refinements on an already-published page.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

Page UUID

Request Body schema: application/json
required
object

Microagent ID → payload dict for the microagents to run

Responses

Request samples

Content type
application/json
{
  • "microagents": {
    }
}

Content Assistant: AI Content Grading

Grade existing page content against target keywords using AI analysis.

Create or update AI content grader record

Submits a page for AI content grading. Grading evaluates the content against target keywords using multiple AI signals. Either url or content (raw HTML) must be supplied - not both.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

Page UUID

Request Body schema: application/json
required
keywords
required
Array of strings non-empty

Target keywords to grade the content against

url
string or null <uri>

URL to fetch and grade (mutually exclusive with content)

content
string or null

Raw HTML content to grade (mutually exclusive with url)

content_last_updated_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "keywords": [
    ],
  • "html_analysis": {
    },
  • "result": { },
  • "content": "string",
  • "content_last_updated_at": "2019-08-24T14:15:22Z",
  • "content_last_graded_at": "2019-08-24T14:15:22Z",
  • "task_status": "PENDING",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List AI content grader records

Returns all AI content grader score records for the authenticated account.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 20

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Content Assistant: Semantic Grader

Semantic SEO analysis that scores a URL or HTML document against a keyword using SERP entity and semantic analysis. Returns ensemble and per-method scores.

List semantic grader analyses

Returns all semantic grader records for the authenticated account, ordered by most recent.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 20
ordering
string

Field to order by. Example: -created_at

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Create a semantic grader analysis

Initiates a semantic SEO analysis for a URL and keyword combination. Retrieves SERP competitors, extracts entities and topics, and scores the target URL against the semantic field of SERP results. Processing is asynchronous - poll the detail endpoint for task_status = SUCCESS.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
string or null <uri>

URL to analyse (mutually exclusive with html_text)

keyword
required
string <= 160 characters

Target keyword for semantic analysis

country_code
string or null

ISO country code (e.g. "us", "gb")

location
string or null

Location name (e.g. "United States")

location_id
integer or null

SearchAtlas location ID (e.g. 2840 for United States)

html_text
string or null

Raw HTML text to analyse (mutually exclusive with url)

process_serps
boolean
Default: false

Whether to process SERP competitors for scoring (consumes more quota)

serps_source
string
Default: "google"
Enum: "google" "bing"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "html_analysis": {
    },
  • "target_keyword": { },
  • "task_status": "PENDING",
  • "overall_score": 0,
  • "ensemble_score": 0,
  • "public_share_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get semantic grader analysis

Returns the full semantic grader record including all scoring method results and ensemble score.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "html_analysis": {
    },
  • "target_keyword": { },
  • "task_status": "PENDING",
  • "overall_score": 0,
  • "ensemble_score": 0,
  • "public_share_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "scoring_methods": { },
  • "serp_data": { }
}

Delete a semantic grader analysis

Permanently deletes the semantic grader record and all associated scoring data.

Authorizations:
apiKeyAuth

Responses

Reprocess semantic grader analysis

Triggers a fresh reprocessing of the semantic analysis for this record. Consumes quota. Use when SERP data has changed or the user wants updated scores.

Authorizations:
apiKeyAuth
Request Body schema: application/json
object

No body fields required - reprocessing uses the record''s existing URL and keyword

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": 0,
  • "html_analysis": {
    },
  • "target_keyword": { },
  • "task_status": "PENDING",
  • "overall_score": 0,
  • "ensemble_score": 0,
  • "public_share_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Content Assistant: Domain Knowledge Networks

Hierarchical website topic structures. A DKN maps a domain's full content architecture (root → categories → subcategories → leaf pages). Nodes can trigger AI article generation.

List Domain Knowledge Networks

Returns all DKN records (business info + domain configuration) for the authenticated account.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get DKN overview metrics

Returns aggregated metrics across pages tied to all DKNs for the account: total_pages, published_pages, pending_pages, domain_content_score, total_nodes, pending_generation.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "total_pages": 0,
  • "published_pages": 0,
  • "pending_pages": 0,
  • "domain_content_score": 0,
  • "total_nodes": 0,
  • "pending_generation": 0
}

Phase 1 - Create DKN (business info)

Creates a DKN record with domain URL and business details. Triggers async site explorer processing for the domain. Phase 1 must complete before Phase 2.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

Website URL to build DKN for

business_name
required
string
location
required
string

Business location name (e.g. "United States")

location_id
required
integer

SearchAtlas location ID (e.g. 2840)

language
required
string

Primary language code (e.g. "en")

otto_project_uuid
string or null <uuid>

Optional OTTO project to link this DKN to

Responses

Request samples

Content type
application/json
{
  • "url": "https://example.com",
  • "business_name": "Example Corp",
  • "location": "United States",
  • "location_id": 2840,
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "http://example.com",
  • "hostname": "string",
  • "business_name": "string",
  • "business_purpose": "string",
  • "main_offers": "string",
  • "monetization": "string",
  • "target_audience": "string",
  • "location": "string",
  • "location_id": 0,
  • "language": "string",
  • "central_entity": "string",
  • "central_search_intent": "string",
  • "core_section_definition": "string",
  • "outer_section_definition": "string",
  • "topic_map_content": [ ],
  • "task_status": "PENDING",
  • "is_generating": true,
  • "phase_1_created": true,
  • "phase_2_created": true,
  • "otto_project_uuid": "533c63db-12c5-4866-a229-0db1c3241679",
  • "customer_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Phase 2 - Generate topical maps from DKN

Triggers AI generation of topical maps from the DKN business context. Creates cluster nodes representing the site architecture. Pass ?force=true as a query parameter to force regeneration even when nodes already exist. If nodes with valid keywords already exist and force is not set, the call is a no-op and returns the current DKN record immediately.

Authorizations:
apiKeyAuth
query Parameters
force
boolean
Default: false

Force full regeneration even if nodes already exist

Request Body schema: application/json
object

No body fields required - configuration is derived from the DKN record

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "http://example.com",
  • "hostname": "string",
  • "business_name": "string",
  • "business_purpose": "string",
  • "main_offers": "string",
  • "monetization": "string",
  • "target_audience": "string",
  • "location": "string",
  • "location_id": 0,
  • "language": "string",
  • "central_entity": "string",
  • "central_search_intent": "string",
  • "core_section_definition": "string",
  • "outer_section_definition": "string",
  • "topic_map_content": [ ],
  • "task_status": "PENDING",
  • "is_generating": true,
  • "phase_1_created": true,
  • "phase_2_created": true,
  • "otto_project_uuid": "533c63db-12c5-4866-a229-0db1c3241679",
  • "customer_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update DKN business info

Updates business info fields on a DKN (e.g. business_purpose, target_audience, language). If the URL/hostname changes, all derived fields are reset and site explorer reprocesses. Field updates to business info fields also trigger automatic DKN regeneration.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
string <uri>
business_name
string
business_purpose
string or null
main_offers
string or null
monetization
string or null
target_audience
string or null
location
string
location_id
integer
language
string
otto_project_uuid
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "business_name": "string",
  • "business_purpose": "string",
  • "main_offers": "string",
  • "monetization": "string",
  • "target_audience": "string",
  • "location": "string",
  • "location_id": 0,
  • "language": "string",
  • "otto_project_uuid": "533c63db-12c5-4866-a229-0db1c3241679"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "http://example.com",
  • "hostname": "string",
  • "business_name": "string",
  • "business_purpose": "string",
  • "main_offers": "string",
  • "monetization": "string",
  • "target_audience": "string",
  • "location": "string",
  • "location_id": 0,
  • "language": "string",
  • "central_entity": "string",
  • "central_search_intent": "string",
  • "core_section_definition": "string",
  • "outer_section_definition": "string",
  • "topic_map_content": [ ],
  • "task_status": "PENDING",
  • "is_generating": true,
  • "phase_1_created": true,
  • "phase_2_created": true,
  • "otto_project_uuid": "533c63db-12c5-4866-a229-0db1c3241679",
  • "customer_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Start DKN Vibe Code session

Initiates an AI-assisted DKN configuration session using a natural language prompt. Returns a transaction ID for polling the result.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
prompt
required
string

Natural language description of desired DKN configuration

Responses

Request samples

Content type
application/json
{
  • "prompt": "string"
}

Response samples

Content type
application/json
{
  • "task_id": "string"
}

Check Vibe Code task status

Polls the status and result of a DKN Vibe Code session.

Authorizations:
apiKeyAuth
path Parameters
taskId
required
string

Vibe Code task ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "task_status": "PENDING",
  • "user_prompt": "string",
  • "parsed_json": { },
  • "task_error_message": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List DKN nodes

Returns DKN nodes for the authenticated account. Supports filtering by DKN, page type, category, subcategory, and generation status.

Authorizations:
apiKeyAuth
query Parameters
domain_knowledge_network
integer

Filter by DKN ID

page
integer
Default: 1
page_size
integer
Default: 50
is_leaf
boolean

Filter to leaf nodes only (pages)

category
string
page_type
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "domain_knowledge_network": {
    },
  • "results": [
    ]
}

Get DKN tree view

Returns the full hierarchical tree structure of nodes for a DKN. Uses a CTE (Common Table Expression) SQL query for efficient tree traversal. Each node contains nested children recursively.

Authorizations:
apiKeyAuth
query Parameters
domain_knowledge_network
required
integer

DKN ID to get tree for

Responses

Response samples

Content type
application/json
{
  • "domain_knowledge_network": {
    },
  • "tree": [
    ]
}

Get filter options for DKN nodes

Returns available filter values (categories, page types, subcategories) for the DKN node list.

Authorizations:
apiKeyAuth
query Parameters
domain_knowledge_network
required
integer

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ],
  • "page_types": [
    ],
  • "subcategories": [
    ]
}

Update a DKN node

Partially update a DKN node (e.g. page_title, page_desc, target_keywords, slug, content_brief).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
page_title
string
page_desc
string or null
slug
string or null
target_keywords
Array of strings
content_brief
object or null
parent_node
integer or null
is_leaf
boolean
is_root
boolean

Responses

Request samples

Content type
application/json
{
  • "page_title": "string",
  • "page_desc": "string",
  • "slug": "string",
  • "target_keywords": [
    ],
  • "content_brief": { },
  • "parent_node": 0,
  • "is_leaf": true,
  • "is_root": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "domain_knowledge_network": {
    },
  • "parent_node": 0,
  • "children_nodes": [
    ],
  • "is_root": true,
  • "is_leaf": true,
  • "is_category": true,
  • "is_subcategory": true,
  • "section": "string",
  • "item": "string",
  • "page_title": "string",
  • "page_desc": "string",
  • "slug": "string",
  • "page_type": "string",
  • "category": "string",
  • "subcategory": "string",
  • "target_keywords": [
    ],
  • "entities": [ ],
  • "query_networks": { },
  • "factuality": { },
  • "internal_link_structure": { },
  • "content_brief": { },
  • "components": { },
  • "meta_tags": { },
  • "article_uuid": "b834f734-af34-4e26-9bd8-f9290412b313",
  • "article_status": "string",
  • "otto_project_uuid": "533c63db-12c5-4866-a229-0db1c3241679",
  • "depth": 0,
  • "parent_path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a DKN node

Deletes a DKN node and recalculates the parent node's is_leaf flag. Any linked CGenius content or content fragments are preserved.

Authorizations:
apiKeyAuth

Responses

Generate article for a DKN node

Creates a CGenius content record and starts the full generation pipeline for a single DKN node. The node's page_title and target_keywords are used as the content topic. Returns the new CGeniusContent record.

Either project or brand_vault_uuid can be supplied for AI settings context (not both).

Authorizations:
apiKeyAuth
Request Body schema: application/json
object (CGeniusSettingsContext)
object

Microagent ID → payload dict

project
integer or null

Project ID for AI settings (mutually exclusive with brand_vault_uuid)

brand_vault_uuid
string or null <uuid>

BrandVault UUID for AI settings (mutually exclusive with project)

content_topic
string or null

Override content topic (defaults to node page_title)

user_prompt
string or null

Additional custom instructions for this article

target_keywords
Array of strings <= 3 items

Responses

Request samples

Content type
application/json
{
  • "settings_context": {
    },
  • "microagents": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "content_topic": "string",
  • "type": "string",
  • "page": 0,
  • "settings_context": {
    },
  • "is_bulk_generation": true,
  • "was_published_to_editor": true,
  • "is_headings_imported": true,
  • "fully_complete": true,
  • "content_ready_for_preview": true,
  • "word_count": 0,
  • "word_count_after_microagents": 0,
  • "reasoning_seconds": 0,
  • "information_retrieval": { },
  • "information_retrieval_task_status": "PENDING",
  • "information_retrieval_started_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_finished_at": "2019-08-24T14:15:22Z",
  • "information_retrieval_error_message": "string",
  • "headings_outline": { },
  • "headings_outline_raw": { },
  • "headings_outline_task_status": "PENDING",
  • "headings_outline_started_at": "2019-08-24T14:15:22Z",
  • "headings_outline_finished_at": "2019-08-24T14:15:22Z",
  • "headings_outline_error_message": "string",
  • "content_brief": { },
  • "content_brief_task_status": "PENDING",
  • "content_brief_started_at": "2019-08-24T14:15:22Z",
  • "content_brief_finished_at": "2019-08-24T14:15:22Z",
  • "content_brief_error_message": "string",
  • "citations": { },
  • "citations_task_status": "PENDING",
  • "citations_started_at": "2019-08-24T14:15:22Z",
  • "citations_finished_at": "2019-08-24T14:15:22Z",
  • "html_content": "string",
  • "html_content_task_status": "PENDING",
  • "html_content_started_at": "2019-08-24T14:15:22Z",
  • "html_content_finished_at": "2019-08-24T14:15:22Z",
  • "html_content_error_message": "string",
  • "microagents": [
    ],
  • "microagents_task_status": "PENDING",
  • "microagents_started_at": "2019-08-24T14:15:22Z",
  • "microagents_finished_at": "2019-08-24T14:15:22Z",
  • "microagents_error_message": "string",
  • "image_generation_task_status": "PENDING",
  • "links_insertion": { },
  • "links_insertion_task_status": "PENDING",
  • "inserted_links": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by_user": 0,
  • "customer": 0
}

Bulk generate articles for DKN nodes

Creates CGenius content records and starts generation for 2-50 DKN nodes at once. All nodes must belong to the authenticated customer. Either project or brand_vault_uuid provides AI settings (mutually exclusive).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
node_ids
required
Array of integers [ 2 .. 50 ] items

List of DKN node IDs to generate articles for (2-50)

project
integer or null

Project ID (mutually exclusive with brand_vault_uuid)

brand_vault_uuid
string or null <uuid>

BrandVault UUID (mutually exclusive with project)

user_prompt
string or null

Additional instructions applied to all articles

Responses

Request samples

Content type
application/json
{
  • "node_ids": [
    ],
  • "brand_vault_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

Content type
application/json
{
  • "created_count": 0,
  • "ids": [
    ]
}

Content Assistant: CMS Publishing

Connect SearchAtlas to external CMS platforms (WordPress, Shopify, etc.) via UCMS plugin connectors. Push articles from the editor directly to connected CMS.

Get CMS connectors available for a page

Returns CMS connectors (with connection details) that can be used to publish the given page.

Authorizations:
apiKeyAuth
path Parameters
id
required
integer

Page ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get CMS push form schema

Returns the JSON schema for the CMS push form for a specific connector. Used by the frontend to dynamically render the publishing form fields.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string <uuid>
query Parameters
connector_id
required
integer

Responses

Response samples

Content type
application/json
{ }

Push a page to a CMS

Publishes the page content to the connected CMS. The request body is shaped by the connector's push form schema (retrieved via push-form-schema). Returns the remote page ID and URL after successful publication.

Authorizations:
apiKeyAuth
path Parameters
pageId
required
string <uuid>
Request Body schema: application/json
required
connector_id
required
integer

CMS connector ID to publish through

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "connector_id": 0
}

Response samples

Content type
application/json
{}

Get dynamic CMS custom fields

Returns dynamic custom fields schema for a connector - typically called after initial push form fields are filled to load conditional fields.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string <uuid>
query Parameters
connector_id
required
integer
Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Content Assistant: Topical Maps

Generate topical authority maps for a seed keyword. Maps produce clustered keyword groups and title suggestions that seed article creation workflows.

Update article entry in a topical map

Links or updates an article (page) to a title slot within the topical map. Can set page_uuid, update the title name, or mark the entry for deletion.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
title_uuid
required
string <uuid>

UUID of the title slot within the topical map

page_uuid
string or null <uuid>

UUID of the page/article to link to this title slot

wp_published_at_url
string or null <uri>

URL where the article was published in WordPress

title_name
string or null

Optional updated title text

should_delete
boolean or null

Set true to remove this article from the title slot

Responses

Request samples

Content type
application/json
{
  • "title_uuid": "550e8400-e29b-41d4-a716-446655440000",
  • "page_uuid": "660e8400-e29b-41d4-a716-446655440001",
  • "title_name": "10 Proven SEO Strategies for 2025"
}

Store user-selected titles

Persists the user's selection of which title suggestions to use for article creation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
uuids
Array of strings <uuid> [ items <uuid > ]

UUIDs of selected title entries

Responses

Request samples

Content type
application/json
{
  • "uuids": [
    ]
}

Bulk create articles from topical map

Creates and starts CGenius generation for multiple articles from selected topical map title slots. Each entry can have its own settings_context override, or use the global settings.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string <uuid>

Topical map UUID

Request Body schema: application/json
required
object or null (CGeniusSettingsContext)
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "global_settings_context": {
    },
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "created_count": 0
}

Bulk create outlines from topical map

Creates AI content outlines (without full HTML generation) for multiple topical map entries.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string <uuid>

Topical map UUID

Request Body schema: application/json
required
object or null (CGeniusSettingsContext)
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "global_settings_context": {
    },
  • "entries": [
    ]
}

Export topical map to Google Sheet

Exports the topical map data (clusters, keywords, titles, article URLs) to a Google Spreadsheet and returns the sheet URL. No request body is required.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{}

List topical authority maps

Returns all topical authority maps for the authenticated account.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 20
project
integer

Filter by project ID (use 0 for uncategorized)

ordering
string

Field to sort by. Example: -created_at

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Create a topical authority map

Generates a topical authority map for the given content topic. The map clusters related keywords and generates article title suggestions. Processing is asynchronous.

clusters_count, keywords_count, and titles_count must each be between 1 and 10.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
content_topic
required
string

Seed topic for the topical authority map

content_page
string or null

Optional target page URL

clusters_count
required
integer [ 1 .. 10 ]

Number of topic clusters to generate

keywords_count
required
integer [ 1 .. 10 ]

Number of keywords per cluster

titles_count
required
integer [ 1 .. 10 ]

Number of article title suggestions per cluster

language_code
required
string or null

Language code (e.g. "en", "es") - null defaults to English

country_code
string or null

ISO country code for localised SERP data (e.g. "us")

otto_project
string or null <uuid>

OTTO project UUID to associate this map with

project
integer or null

CA project ID (use 0 for uncategorized)

brand_vault_uuid
string or null <uuid>

BrandVault UUID for AI style context

Responses

Request samples

Content type
application/json
{
  • "content_topic": "SEO for e-commerce",
  • "clusters_count": 5,
  • "keywords_count": 5,
  • "titles_count": 5,
  • "language_code": "en",
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "content_topic": "string",
  • "content_page": "string",
  • "clusters_count": 0,
  • "keywords_count": 0,
  • "titles_count": 0,
  • "language_code": "string",
  • "country_code": "string",
  • "otto_project": "cad3e205-7af9-43d3-8cbd-65acb43e0af5",
  • "project": 0,
  • "folder_name": "string",
  • "task_status": "PENDING",
  • "formatted_data": { },
  • "google_spreadsheet_url": "http://example.com",
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "processing_ended_at": "2019-08-24T14:15:22Z",
  • "redirect_url": "http://example.com",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "brand_vault_name": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get a topical authority map

Returns the full topical map including formatted_data with clusters, keywords, and title suggestions.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "content_topic": "string",
  • "content_page": "string",
  • "clusters_count": 0,
  • "keywords_count": 0,
  • "titles_count": 0,
  • "language_code": "string",
  • "country_code": "string",
  • "otto_project": "cad3e205-7af9-43d3-8cbd-65acb43e0af5",
  • "project": 0,
  • "folder_name": "string",
  • "task_status": "PENDING",
  • "formatted_data": { },
  • "google_spreadsheet_url": "http://example.com",
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "processing_ended_at": "2019-08-24T14:15:22Z",
  • "redirect_url": "http://example.com",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "brand_vault_name": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a topical authority map

Update metadata fields (project, redirect_url, etc.) on an existing topical map.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
project
integer or null

Project ID (use 0 for uncategorized)

redirect_url
string or null <uri>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "content_topic": "string",
  • "content_page": "string",
  • "clusters_count": 0,
  • "keywords_count": 0,
  • "titles_count": 0,
  • "language_code": "string",
  • "country_code": "string",
  • "otto_project": "cad3e205-7af9-43d3-8cbd-65acb43e0af5",
  • "project": 0,
  • "folder_name": "string",
  • "task_status": "PENDING",
  • "formatted_data": { },
  • "google_spreadsheet_url": "http://example.com",
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "processing_ended_at": "2019-08-24T14:15:22Z",
  • "redirect_url": "http://example.com",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "brand_vault_name": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a topical authority map

Permanently deletes the topical authority map and all its cluster/keyword/title data. Linked pages are not deleted.

Authorizations:
apiKeyAuth

Responses

Content Assistant: File Uploads

Upload images and files to GCP storage for use in content pages.

Upload an image to GCP storage

Uploads an image file to GCP Cloud Storage and returns the public URL. Supported formats: JPEG, PNG, WEBP, GIF. Maximum file size: 5 MiB. Images can be reformatted on upload (WEBP default) and optionally constrained to an aspect ratio.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
image
required
string <binary>

Image file (max 5 MiB)

format
string
Default: "WEBP"
Enum: "WEBP" "JPEG" "PNG" "GIF"

Output format for the stored image

mode
string
Default: "PERSISTENT"
Enum: "PERSISTENT" "TEMPORARY"

PERSISTENT = stored in StoredImage model with GCS URL; TEMPORARY = ephemeral GCP upload (no DB record)

aspect_ratio
number or null <decimal> [ 0.1 .. 5 ]

Optional aspect ratio constraint (width/height)

validation
string or null
Enum: "GBP" null

Apply extra validation rules (e.g. GBP min 256px dimensions)

Responses

Response samples

Content type
application/json
{}

Universal CMS: Overview

CMS connector management for publishing content to external platforms including WordPress, Shopify, HubSpot, Joomla, and more. Discover supported plugins, retrieve connector schemas, and manage connections.

Base URL: https://ucmsi.searchatlas.com

CMS: Plugins

Discover supported CMS plugins and retrieve per-plugin schemas

List supported CMS plugins

Returns all CMS plugins that are active and supported for content publishing. Each plugin entry includes auth types, publish modes, capabilities, and logo URL.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CMS: Connectors

Manage saved CMS connector credentials per OTTO project

Get CMS connector

Returns a single saved CMS connector by ID.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "plugin": "hubspot",
  • "plugin_version": "1.0",
  • "config": { },
  • "otto_uuid": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z"
}

Update CMS connector

Partially update a saved CMS connector (credentials, config, or name).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
Bearer Token (HubSpot, Joomla) (object) or Basic Auth (Drupal, Magento) (object) or API Token (Webflow) (object) or OAuth2 (Webflow) (object) or API Key (Wix) (object) or Token (Contentful) (object) or Private Token (GoHighLevel) (object) (Credentials)
object
name
string

Responses

Request samples

Content type
application/json
{
  • "credentials": {
    },
  • "config": { },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "plugin": "hubspot",
  • "plugin_version": "1.0",
  • "config": { },
  • "otto_uuid": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z"
}

CMS: Schema

Retrieve push-form schemas, dynamic field options, and OTTO SEO suggestions

Get plugin schema

Returns the full schema for a specific CMS plugin, including auth schemes, credential schema, publish modes, config schema, and capabilities. Pass ?plugin={pluginSlug} to specify the plugin (e.g. hubspot, drupal, webflow).

Authorizations:
apiKeyAuth
query Parameters
plugin
required
string
Example: plugin=hubspot

Plugin slug (e.g. hubspot, drupal, webflow, wix, contentful)

Responses

Response samples

Content type
application/json
{
  • "plugin": {
    },
  • "version": {
    },
  • "auth_schemes": [
    ],
  • "credential_schema": { },
  • "publish_modes": [
    ],
  • "config_schema": { },
  • "capabilities": { }
}

Google Search Console: Overview

Access Google Search Console data including site properties, keyword and page performance metrics, search analytics, site events, page groups, and integrations with Google Analytics, Google Ads, and Facebook Ads.

Base URL: https://gsc.searchatlas.com

GSC: Sites & Properties

List, manage, and configure Google Search Console site properties

List GMB locations

Returns all Google My Business locations for report builder integration.

Authorizations:
apiKeyAuth
query Parameters
account_id
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List site properties (v4)

Returns paginated GSC site properties with performance metrics for two comparison periods. Supports filtering by active state, country code, search query, and ordering.

Authorizations:
apiKeyAuth
query Parameters
period1_start
required
string <date>

Start date of the reference period (YYYY-MM-DD)

period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>
page_size
integer
Default: 10
page_number
integer
Default: 1
country_code
string <= 2 characters
active
boolean or null
search
string
order_by
string

Ordering field. Options: total_impressions, -total_impressions, total_traffic, -total_traffic, total_kw, -total_kw, avg_ranking, -avg_ranking, created_at, -created_at

aggregation
string
Default: "daily"
Enum: "daily" "weekly"

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "active_sites_count": 0,
  • "inactive_sites_count": 0,
  • "results": [
    ]
}

Get search performance data load status

Returns the current data load status for a site property's search analytics pipeline.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string

GSC site property URL (e.g. https://example.com/ or sc-domain:example.com)

country_code
string
Default: ""

Responses

Response samples

Content type
application/json
{
  • "selected_property": "string",
  • "status": "PENDING",
  • "last_updated": "2019-08-24T14:15:22Z",
  • "data_available_from": "2019-08-24"
}

GSC: Reports & Metrics

Core performance reports, organic search metrics, and site property analytics

Get core GSC performance report

Returns aggregated clicks, impressions, CTR, and average position for a site property over two comparison periods. Supports keyword and page filtering.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "selected_property": "string",
  • "period1": {
    },
  • "period2": {
    },
  • "chart_data": [
    ]
}

Get site property performance summary

Returns top-level performance metrics for a site property with comparison against previous period.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string
country_code
string
Default: ""
limit
integer
Default: 10

Responses

Response samples

Content type
application/json
{
  • "selected_property": "string",
  • "total_clicks": 0,
  • "total_impressions": 0,
  • "avg_ctr": 0,
  • "avg_position": 0
}

GSC: Keywords

Keyword ranking reports, position changes, cannibalization, and historical performance

Get keywords performance report

Returns paginated keyword-level GSC performance data (clicks, impressions, CTR, position) for two comparison periods. Supports keyword/page include/exclude filters.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 25
ordering
string

Field to order by. Options: clicks, -clicks, impressions, -impressions, ctr, -ctr, position, -position

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Update branded keywords list

Replaces the branded keywords list for a site property. These keywords are used to segment branded vs non-branded traffic in reports.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
selected_property
required
string

GSC site property URL

country_code
string
Default: ""
keywords
required
Array of strings

List of branded keyword strings

Responses

Request samples

Content type
application/json
{
  • "selected_property": "https://example.com/",
  • "country_code": "",
  • "keywords": [
    ]
}

Get keyword rankings breakdown

Returns keyword position distribution (positions 1, 2-5, 6-10, 11-20, etc.) for a site property.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string
country_code
string
Default: ""
period1_start
required
string <date>
period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>

Responses

Response samples

Content type
application/json
{
  • "period1": {
    },
  • "period2": {
    }
}

Get keyword historical performance

Returns click, impression, CTR, and position history for a specific keyword over time.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string
country_code
string
Default: ""
keyword
required
string
period1_start
required
string <date>
period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>

Responses

Response samples

Content type
application/json
{
  • "chart_data": [
    ]
}

Get position keyword changes report

Returns keywords that gained or lost positions over a comparison period, with change magnitude.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 25
ordering
string

Responses

Response samples

Content type
application/json
{}

GSC: Pages

Page-level performance, top pages overview, and historical page data

Get pages performance report

Returns paginated page-level GSC performance data (clicks, impressions, CTR, position) for two comparison periods with include/exclude page filtering.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 25
ordering
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Get page historical performance (v2)

Returns click, impression, CTR, and position history for a specific page URL over time.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string
country_code
string
Default: ""
page
required
string

Page URL to retrieve historical data for

period1_start
required
string <date>
period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>

Responses

Response samples

Content type
application/json
{
  • "chart_data": [
    ]
}

Get page historical performance summary (v3)

Returns an aggregate summary of historical performance metrics for a page with v3 date handling.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string
country_code
string
Default: ""
period1_start
string <date>
period1_end
string <date>
period2_start
required
string <date>
period2_end
required
string <date>

Responses

Response samples

Content type
application/json
{
  • "chart_data": [
    ]
}

Get keywords for a page's historical performance (v3)

Returns the top keywords driving traffic to a specific page, with historical position data.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string
country_code
string
Default: ""
period1_start
string <date>
period1_end
string <date>
period2_start
required
string <date>
period2_end
required
string <date>
page
integer
Default: 1
page_size
integer
Default: 25

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

GSC: Page Groups

Group pages together for aggregate reporting and performance tracking

List page groups

Returns all page groups configured for the authenticated user's site properties.

Authorizations:
apiKeyAuth
query Parameters
selected_property
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a page group

Creates a new page group for a site property. Page groups allow you to aggregate performance metrics across a set of related pages.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
site_property
required
string

GSC site property URL this group belongs to

name
required
string
color
required
string

Hex color code (e.g. #3B82F6)

icon
string or null
pages
required
Array of strings

List of page URL paths to include in this group

Responses

Request samples

Content type
application/json
{
  • "site_property": "https://example.com/",
  • "name": "Blog Posts",
  • "color": "#3B82F6",
  • "icon": "document",
  • "pages": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "color": "string",
  • "icon": "string",
  • "pages_count": 0
}

Update a page group

Updates the name, color, icon, or pages list for a page group.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string
color
string
icon
string or null
pages
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "color": "string",
  • "icon": "string",
  • "pages": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "color": "string",
  • "icon": "string",
  • "pages_count": 0
}

GSC: Events

Site property events - mark and track significant changes affecting performance

List site property events

Returns all events logged for a specific site property.

Authorizations:
apiKeyAuth
query Parameters
selected_property
required
string
country_code
string
Default: ""

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a site property event

Logs a new event (e.g., algorithm update, content change, technical fix) for a site property.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
site_property
required
string

GSC site property URL

country_code
string
Default: ""
name
required
string

Descriptive event name

event_date
required
string <date>
event_type
required
string

Event category: content, technical, algorithm, link, other

Responses

Request samples

Content type
application/json
{
  • "site_property": "https://example.com/",
  • "country_code": "",
  • "name": "Published homepage redesign",
  • "event_date": "2024-03-15",
  • "event_type": "content"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "event_date": "2019-08-24",
  • "event_type": "string",
  • "site_property": "string",
  • "country_code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get a site property event

Returns the details of a specific site property event.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "event_date": "2019-08-24",
  • "event_type": "string",
  • "site_property": "string",
  • "country_code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a site property event

Updates the name, date, or type of a site property event.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
site_property
required
string

GSC site property URL

country_code
string
Default: ""
name
required
string

Descriptive event name

event_date
required
string <date>
event_type
required
string

Event category: content, technical, algorithm, link, other

Responses

Request samples

Content type
application/json
{
  • "site_property": "string",
  • "country_code": "",
  • "name": "string",
  • "event_date": "2019-08-24",
  • "event_type": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "event_date": "2019-08-24",
  • "event_type": "string",
  • "site_property": "string",
  • "country_code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a site property event

Permanently removes a site property event by ID. The event will no longer appear in the events overview chart.

Authorizations:
apiKeyAuth

Responses

GSC: Analytics

Google Analytics settings and reporting integration

List GA4 properties

Returns Google Analytics 4 properties available for report builder integration.

Authorizations:
apiKeyAuth
query Parameters
country_code
string <= 2 characters
query
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

GSC: Google Ads

Google Ads customer account management and metrics

List Google Ads accounts for report builder

Returns a simplified list of Google Ads accounts for use in report builder dropdowns.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

GSC: Facebook Ads

Facebook Ads account management, pages, and Instagram accounts

List Facebook Ads accounts for report builder

Returns a simplified dropdown list of Facebook Ads accounts for report builder.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Facebook pages

Returns all Facebook Pages connected to the authenticated user's ad account.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[]

List Instagram accounts

Returns all Instagram professional accounts connected via the Facebook Ads integration.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List LinkedIn accounts

Returns all LinkedIn ad accounts connected to the authenticated user.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Twitter/X accounts

Returns all Twitter/X accounts connected to the authenticated user.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Keyword Explorer: Overview

Keyword research and analysis tools. Discover content ideas with AI-powered clustering, manage keyword lists, run keyword gap analyses against competitors, track keyword rankings over time, and analyze search query visibility with QUEST.

Base URL: https://keyword.searchatlas.com

Keyword Explorer: Content Ideas

AI-powered content idea clusters from a seed keyword and target domain

Create a content ideas plan

Triggers AI-powered content clustering for a seed keyword. Returns an existing plan if one already exists for the same keyword/domain/country combination. Processing is asynchronous - poll the detail endpoint for processing_status: SUCCESS.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keyword
required
string

Seed keyword to generate content ideas for

domain
string or null

Target domain to focus content ideas on (e.g., example.com)

country_code
string or null <= 2 characters

ISO 2-letter country code for localized search data

customer_id
integer or null
brand_vault_id
string or null <uuid>

Optional Brand Vault ID to scope content to a brand's voice

Responses

Request samples

Content type
application/json
{
  • "keyword": "best running shoes",
  • "domain": "example.com",
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "customer_id": 0,
  • "brand_vault_id": "ac6f29a7-3744-46f7-83b9-4cc2cddbafe1",
  • "keyword": "string",
  • "domain": "string",
  • "country_code": "string",
  • "cluster_count": 0,
  • "public_share_hash": "string",
  • "processing_completed_at": "2019-08-24T14:15:22Z",
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "is_archived": true,
  • "searched_on": "2019-08-24T14:15:22Z",
  • "processing_status": "PENDING"
}

Get content idea plan

Returns full content idea plan with cluster data and processing status. Poll until processing_status is SUCCESS.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "customer_id": 0,
  • "brand_vault_id": "ac6f29a7-3744-46f7-83b9-4cc2cddbafe1",
  • "keyword": "string",
  • "domain": "string",
  • "country_code": "string",
  • "cluster_count": 0,
  • "public_share_hash": "string",
  • "processing_completed_at": "2019-08-24T14:15:22Z",
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "is_archived": true,
  • "searched_on": "2019-08-24T14:15:22Z",
  • "processing_status": "PENDING",
  • "clusters": [
    ]
}

Archive a content idea plan

Marks a content idea plan as archived so it no longer appears in the active list.

Authorizations:
apiKeyAuth

Responses

Keyword Explorer: Keyword Lists

Keyword detail lookups, bulk URL metrics, and keyword metadata

Get keyword detail data

Returns comprehensive keyword detail data including search volume, difficulty, CPC, SERP overview, related keywords, search intent, and historical volume trends.

Authorizations:
apiKeyAuth
query Parameters
keyword
required
string

The keyword to look up

country_code
string <= 2 characters
Default: ""

ISO 2-letter country code (e.g., us, gb, de)

site_property
string or null

Optional GSC site property URL to cross-reference rankings

location_id
integer or null

Specific geo-location ID for local SERP data

serp_freshness_days
integer or null

Max age in days for cached SERP data

serp_count
integer or null

Number of SERP results to include

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "keyword": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "public_share_hash": "string",
  • "difficulty": 0,
  • "search_volume": 0,
  • "global_volume": 0,
  • "cpc": 0,
  • "search_volume_data": [
    ],
  • "related_keywords": [
    ],
  • "autocomplete": [
    ],
  • "questions": [
    ],
  • "serp_overview": [],
  • "task_status": "PENDING",
  • "top_countries_search_volume": [
    ]
}

Get bulk URL/domain metrics

Returns domain authority, organic traffic, referring domains, and other metrics for a list of URLs or domains in a single request.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
urls
required
Array of strings

List of domain names or URLs to retrieve metrics for

include_location
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "urls": [
    ],
  • "include_location": false
}

Response samples

Content type
application/json
[
  • {
    }
]

Keyword Explorer: Keyword Gap Analysis

Find keyword opportunities your competitors rank for but you don't

List keyword gap analysis history

Returns all keyword gap analyses created by the authenticated user.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create keyword gap analysis

Identifies keywords that competitor websites rank for but the primary website does not. Accepts 1-4 competitor websites with a country code for location-specific data. Results are fetched asynchronously - returns 202 with should_repoll: true on cache miss.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
object (WebsiteWithScope)
required
Array of objects (WebsiteWithScope) [ 1 .. 4 ] items

Between 1 and 4 competitor websites

country_code
string
Default: ""

ISO 2-letter country code for market-specific gap analysis

Responses

Request samples

Content type
application/json
{
  • "primary_website": {
    },
  • "competitor_websites": [
    ],
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "customer_id": 0,
  • "primary_website": {
    },
  • "competitor_websites": [
    ],
  • "country_code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get keyword gap analysis results

Returns the keyword gap data for a specific analysis. Results may be paginated. Returns 202 with should_repoll: true if data is still processing.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 50
ordering
string

Order by field (e.g., -search_volume, keyword_difficulty)

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "chart_data": [
    ],
  • "total_count": 0,
  • "should_repoll": true
}

Delete keyword gap analysis

Permanently removes a keyword gap analysis entry and its results from the user's account.

Authorizations:
apiKeyAuth

Responses

Keyword Explorer: Rank Tracker

Create and manage keyword rank tracking projects (heatmap grids)

List rank tracker projects (heatmap grids)

Returns all rank tracking projects (local SEO heatmap grids) for the authenticated customer. Each project tracks keyword positions across a geographic grid.

Authorizations:
apiKeyAuth
query Parameters
search
string
update_frequency_days
string
Enum: "DAILY" "EVERY_3_DAYS" "WEEKLY" "MONTHLY"

Filter by refresh interval. Options: DAILY, EVERY_3_DAYS, WEEKLY, MONTHLY

page
integer
Default: 1
page_size
integer
Default: 20

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Keyword Explorer: Quest

LLM Citation Visibility Analysis - generates query-related questions, collects LLM answers with cited sources, validates sources, and tracks domain citation frequency

List QUEST analyses

Returns all QUEST (LLM Citation Visibility Analysis) results for the authenticated user.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a QUEST analysis

Initiates a QUEST analysis for a search query. QUEST analyzes SERP results to understand content format, user intent, and ranking factors for the query. Processing is asynchronous - poll the detail endpoint.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query
required
string

Search query to analyze with QUEST

Responses

Request samples

Content type
application/json
{
  • "query": "best coffee shops in brooklyn"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "query": "string",
  • "task_status": "PENDING",
  • "task_status_updated_at": "2019-08-24T14:15:22Z",
  • "task_error_message": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "dpr_campaign": {
    }
}

Get QUEST analysis details

Returns full QUEST analysis data including SERP results, intent classification, content recommendations, and linked outreach campaign if any. Poll until task_status is SUCCESS.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "query": "string",
  • "task_status": "PENDING",
  • "task_status_updated_at": "2019-08-24T14:15:22Z",
  • "task_error_message": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "dpr_campaign": {
    },
  • "results": {
    }
}

Delete QUEST analysis

Permanently removes a QUEST LLM citation analysis entry and its results from the user's account.

Authorizations:
apiKeyAuth

Responses

Site Explorer: Overview

Competitor and domain research platform. Analyze any website's organic traffic, ranking keywords, backlink profile, topical authority, and Facebook ads data. Compare competitors and track brand signals.

Base URL: https://keyword.searchatlas.com

Site Explorer: Site Explorer v2

Full competitor research - create, retrieve, recrawl, and manage site explorer projects

List site explorer projects

Returns all competitor research projects for the authenticated user, with status and metadata.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 20
search
string
ordering
string

Order by field. Use - prefix for descending.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Create a site explorer project

Initiates a full competitor site analysis for the given URL. Fetches organic traffic, keywords, domain authority, backlinks, and SERP data asynchronously. Returns an existing project if the URL was recently analyzed.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string

Competitor domain or URL to analyze

country_code
string <= 2 characters
Default: ""

ISO 2-letter country code for localized metrics

Responses

Request samples

Content type
application/json
{
  • "url": "competitor.com",
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "country_code": "string",
  • "is_saved": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "processing_status": "PENDING",
  • "organic_traffic": 0,
  • "organic_keywords": 0,
  • "domain_authority": 0,
  • "referring_domains": 0,
  • "traffic_value": 0
}

Bulk create site explorer projects

Creates multiple competitor research projects in a single request.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "urls": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get site explorer project details

Returns full competitor analysis data including organic traffic, keyword counts, domain authority, backlinks, top pages, and processing status.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "country_code": "string",
  • "is_saved": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "processing_status": "PENDING",
  • "organic_traffic": 0,
  • "organic_keywords": 0,
  • "domain_authority": 0,
  • "referring_domains": 0,
  • "traffic_value": 0,
  • "title": "string",
  • "meta_desc": "string",
  • "screenshot_url": "http://example.com",
  • "top_pages": [
    ],
  • "keyword_distribution": {
    },
  • "backlinks_count": 0,
  • "domain_rating": 0
}

Delete site explorer project

Permanently removes a competitor research project and all associated data for the authenticated user.

Authorizations:
apiKeyAuth

Responses

Re-crawl site explorer project

Triggers a fresh data pull for an existing competitor research project. Refreshes keyword rankings, traffic estimates, and backlink data. Consumes quota.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "country_code": "string",
  • "is_saved": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "processing_status": "PENDING",
  • "organic_traffic": 0,
  • "organic_keywords": 0,
  • "domain_authority": 0,
  • "referring_domains": 0,
  • "traffic_value": 0
}

Get extended competitor data

Returns extended data for a competitor research project including detailed keyword distributions, traffic trends, and domain-level SEO signals.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "traffic_trend": [
    ],
  • "keyword_trend": [
    ],
  • "position_distribution_history": [
    ],
  • "anchor_text_distribution": [
    ]
}

Toggle save/unsave a competitor research project

Toggles the saved state of a competitor research project so it appears in the user's saved projects list.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "is_saved": true
}

Get competitor topical authority report

Returns the topical authority breakdown for a competitor, showing which content topics they rank for and their coverage depth. Must be requested first via process-topical-authority-report before data is available.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "topics": [
    ]
}

Site Explorer: Competitor Pressure

Assess competitive pressure for individual keywords or batches

Fetch competitor pressure for a keyword

Calculates the competitive pressure score for a single keyword - a measure of how difficult it is to displace existing top-10 results based on domain authority, content quality, and backlink profiles.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keyword
required
string <= 300 characters

Keyword to calculate competitor pressure for

country_code
string <= 3 characters
Default: "us"
location_id
integer or null

Optional geo-location ID for local SERP pressure

Responses

Request samples

Content type
application/json
{
  • "keyword": "best running shoes",
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "keyword": "string",
  • "country_code": "string",
  • "pressure_score": 0,
  • "top_results": [
    ]
}

Fetch competitor pressure for multiple keywords

Calculates competitive pressure scores for up to 100 keywords in a single request. Results are processed asynchronously - use bulk-status to poll for completion.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keywords
required
Array of strings <= 100 items [ items <= 300 characters ]

Up to 100 keywords to analyze

country_code
string <= 3 characters
Default: "us"
location_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "keywords": [
    ],
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "message": "string"
}

Get competitor pressure status for a keyword

Returns the processing status and result for a single keyword's competitor pressure calculation.

Authorizations:
apiKeyAuth
query Parameters
keyword
required
string
country_code
string <= 3 characters
Default: "us"
location_id
integer or null

Responses

Response samples

Content type
application/json
{
  • "keyword": "string",
  • "status": "PENDING",
  • "result": {
    }
}

Get bulk competitor pressure status

Returns processing status and results for up to 100 keywords in a single request.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keywords
required
Array of strings <= 100 items
country_code
string <= 3 characters
Default: "us"
location_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "keywords": [
    ],
  • "country_code": "us"
}

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Site Explorer: Competitor Discovery

Discover organic competitors, track them, and analyze shared keyword overlap

Get competitor trend data

Returns trend lines showing competitor visibility, shared keywords, and traffic over time. Used to track how competitors are gaining or losing search share.

Authorizations:
apiKeyAuth
query Parameters
site_property
required
string

GSC site property URL or domain

country_code
string
Default: ""
criteria
string
Default: "shared_keywords"
Enum: "shared_keywords" "organic_visibility" "selected_range"
period1_start
string <date>
period1_end
string <date>
period2_start
string <date>
period2_end
string <date>

Responses

Response samples

Content type
application/json
{
  • "competitors": [
    ]
}

Get competitors report

Returns a ranked list of organic competitors for a site property, showing shared keywords, organic visibility overlap, and traffic index for each competitor.

Authorizations:
apiKeyAuth
query Parameters
site_property
required
string
country_code
string
Default: ""
period1_start
required
string <date>
period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>
page
integer
Default: 1
page_size
integer
Default: 25
order_by
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Get competitors keyword usage

Returns keyword usage statistics showing which keywords are shared between the site property and its top organic competitors.

Authorizations:
apiKeyAuth
query Parameters
site_property
required
string
country_code
string
Default: ""
period1_start
required
string <date>
period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>

Responses

Response samples

Content type
application/json
{
  • "total_keywords": 0,
  • "shared_keywords": 0,
  • "unique_to_site": 0,
  • "unique_to_competitors": 0
}

Get top organic keywords for a competitor

Returns the top organic keywords driving traffic to a specific competitor domain.

Authorizations:
apiKeyAuth
query Parameters
site_property
required
string
competitor
required
string

Competitor domain to look up keywords for

country_code
string
Default: ""
period1_start
required
string <date>
period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>
page
integer
Default: 1
page_size
integer
Default: 25

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Get historical competitor data

Returns a historical view of a competitor's position changes, organic visibility, and traffic trends for comparison period analysis.

Authorizations:
apiKeyAuth
query Parameters
site_property
required
string
competitor
required
string
country_code
string
Default: ""
period1_start
required
string <date>
period1_end
required
string <date>
period2_start
required
string <date>
period2_end
required
string <date>
order_by
string

Field to order by. Options: date, -date, competitor_position, -competitor_position, competitor_organic_visibility, -competitor_organic_visibility

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

List tracked competitors

Returns all competitors the user has explicitly added to their tracking list for a site property.

Authorizations:
apiKeyAuth
query Parameters
site_property
required
string
country_code
string
Default: ""

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a tracked competitor

Adds a competitor domain to the tracking list for a specific site property.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
site_property
required
string

GSC site property URL

country_code
string
Default: ""
competitor_domain
required
string

Competitor domain to track (e.g., competitor.com)

Responses

Request samples

Content type
application/json
{}

Remove a tracked competitor

Removes a competitor domain from the tracking list for a site property.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
site_property
required
string

GSC site property URL

country_code
string
Default: ""
competitor_domain
required
string

Competitor domain to track (e.g., competitor.com)

Responses

Request samples

Content type
application/json
{}

Site Explorer: Brand Signals

Analyze and submit brand signal scores for LLM visibility and citation tracking

Retrieve brand signal score

Returns the brand signal score for a domain - measuring how well the brand appears in AI-generated responses (LLM citations), news, and social signals. Returns the most recent cached score.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Domain to retrieve brand signal score for

Responses

Response samples

Content type
application/json
{
  • "domain": "string",
  • "overall_score": 0,
  • "llm_citation_score": 0,
  • "news_score": 0,
  • "social_score": 0,
  • "backlink_authority_score": 0,
  • "llm_citation_trend": [
    ],
  • "last_updated": "2019-08-24T14:15:22Z"
}

Submit domain for brand signal analysis

Triggers a fresh brand signal analysis for a domain. Checks LLM citation presence, news mentions, social signals, and authoritative backlink signals. Processing is asynchronous - re-fetch with retrieve after completion.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string

Domain to analyze (e.g., example.com)

Responses

Request samples

Content type
application/json
{
  • "domain": "example.com"
}

Backlink: Projects

Backlink comparison projects - create, list, update, delete projects with primary and competitor websites

List all backlink projects

Returns all active backlink comparison projects for the authenticated user's account.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a backlink project

Creates a new backlink comparison project with a primary website and optional competitor websites. Triggers asynchronous backlink data retrieval for all websites. Returns an error if a project with the same primary website already exists for this account.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 200 characters
description
string
is_active
boolean
Default: true
timezone
string

IANA timezone string (e.g. America/New_York)

object (PlatformsConfig)
default_approval_type
string
Enum: "AUTO_PUBLISH" "APPROVE_IF_IMAGE" "AI_IMAGES_ONLY" "APPROVE_FOR_PUBLISH"
default_image_source_type
string or null
object (AISettings)
image_prompt
string <= 1000 characters

Convenience alias - merged into ai_settings.image_prompt on save

Responses

Request samples

Content type
application/json
{
  • "primary_website": "example.com",
  • "competitor_websites": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get project details

Returns the primary website and competitor websites with their backlink metrics.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Backlink: Refdomains

Referring domain analysis for project websites

List referring domains for a project

Returns paginated referring domains pointing to the project's primary website. Supports search, filtering by field ranges, and ordering.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 10
search
string

Search phrase to filter by source_url or domain

ordering
string

Field to order by. Prefix with - for descending. Example: -citation_flow

domain_rating
string

Filter by domain rating range. Format: min_to_max. Example: 3to10

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "page": 0,
  • "page_size": 0,
  • "results": [
    ],
  • "primary_website": "string",
  • "task_status": {
    }
}

List referring domains for a competitor

Returns referring domains for a specific competitor website within the project.

Authorizations:
apiKeyAuth
path Parameters
competitor_id
required
integer

Competitor website ID within the project

query Parameters
page
integer
Default: 1
page_size
integer
Default: 10
search
string
ordering
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "page": 0,
  • "page_size": 0,
  • "results": [
    ],
  • "primary_website": "string",
  • "task_status": {
    }
}

Backlink: Refdomains Quota

Check refdomains quota before creating projects

Check refdomains quota

Check if the user has enough refdomains quota to process the given URLs. Returns per-URL refdomain counts and whether quota is sufficient.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
urls
required
Array of strings

List of URLs/domains to check quota for

Responses

Request samples

Content type
application/json
{
  • "urls": [
    ]
}

Response samples

Content type
application/json
{
  • "available_quota": 0,
  • "has_enough_quota": true,
  • "websites": [
    ]
}

Campaigns & Outreach: Overview

Email outreach campaign management for link building and digital PR. Create campaigns, manage email templates, discover and track opportunities, manage contacts, handle inbox conversations, and configure SMTP email accounts.

Base URL: https://keyword.searchatlas.com

Campaigns: Campaigns

Create, manage, and monitor link building outreach campaigns

List outreach campaigns

Returns all outreach campaigns for the authenticated user with pagination and metrics.

Authorizations:
apiKeyAuth
query Parameters
page
integer
Default: 1
page_size
integer
Default: 20
search
string
ordering
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Create an outreach campaign

Creates a new link building outreach campaign with target keywords, email configuration, and scheduling settings. Triggers async processing to find outreach opportunities.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string

Campaign name

customer_id
required
integer
target_keywords
Array of strings <= 20 items

Up to 20 seed keywords for opportunity discovery

linked_email_id
integer or null

Primary linked email account ID for sending

followup_email_ids
Array of integers or null

Follow-up email account IDs

otto_project_id
integer or null

Associate with an OTTO project for automated outreach

questresults_id
integer or null

QUEST analysis ID to seed opportunities from

Responses

Request samples

Content type
application/json
{
  • "name": "Link Building - Running Shoes",
  • "customer_id": 12345,
  • "target_keywords": [
    ],
  • "linked_email_id": 42,
  • "followup_email_ids": [
    ],
  • "otto_project_id": null
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "business_id": 0,
  • "product_id": 0,
  • "status": "string",
  • "status_display": "string",
  • "action": "string",
  • "action_display": "string",
  • "remote_id": "string",
  • "remote_status": "string",
  • "remote_status_display": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "campaign_budget": {
    },
  • "ads_account": {
    },
  • "google_ads_url": "http://example.com",
  • "google_ads_campaign_url": "http://example.com",
  • "negative_keywords_sync_enabled": true,
  • "has_active_adgroups": true,
  • "currency": {
    },
  • "internal_campaign_type": "SEARCH",
  • "clicks": 0,
  • "ctr": 0,
  • "cost": 0,
  • "conversions": 0,
  • "impressions": 0,
  • "remote_start_date": "2019-08-24",
  • "activate_retargeting_auto": true,
  • "landing_page_valid": true,
  • "keyword_clusters_ready": true,
  • "ads_created": true,
  • "campaign_published": true,
  • "location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "advertising_channel_type": "string",
  • "store_goals_enabled": true
}

Get customer linked emails

Returns all email accounts linked to the customer account for use in campaigns.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update daily send limit for a linked email

Updates the daily email sending limit for a specific linked email account.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
id
required
integer

Linked email ID

daily_limit_by_email
required
integer

New daily send limit

Responses

Request samples

Content type
application/json
{
  • "id": 42,
  • "daily_limit_by_email": 50
}

List campaign folders/projects

Returns all campaign project folders for the authenticated customer.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a campaign folder

Creates a new project folder to organize outreach campaigns.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string
customer_id
required
integer

Responses

Request samples

Content type
application/json
{
  • "name": "Q1 Link Building",
  • "customer_id": 12345
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "customer_id": 0
}

Delete a campaign folder

Deletes a campaign project folder.

Authorizations:
apiKeyAuth
query Parameters
id
required
integer

Campaign folder ID to delete

Responses

Get global blacklist

Returns the global domain/email blacklist - domains excluded from all campaigns for this customer.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "blacklisted_domains": [
    ],
  • "blacklisted_emails": [
    ]
}

Update global blacklist

Replaces the global domain/email blacklist for this customer account.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
blacklisted_domains
Array of strings

Full list of blacklisted domains (replaces existing)

blacklisted_emails
Array of strings

Full list of blacklisted email addresses

Responses

Request samples

Content type
application/json
{
  • "blacklisted_domains": [
    ]
}

Remove a linked email account

Disconnects and removes a linked SMTP or OAuth email account from the customer's configuration.

Authorizations:
apiKeyAuth
query Parameters
linked_email_id
required
integer

ID of the linked email to remove

Responses

Get campaign chart data

Returns time-series performance data for a campaign (emails sent, opens, replies) for charting.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "chart_series": [
    ]
}

Update a campaign

Updates campaign settings including name, keywords, and email configuration.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string <= 255 characters
remote_status
string
Enum: "ENABLED" "PAUSED"
negative_keywords_sync_enabled
boolean
bidding_strategy_type
string
target_cpa
number
max_cpc_bid
number
target_roas
number

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "remote_status": "ENABLED",
  • "negative_keywords_sync_enabled": true,
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "business_id": 0,
  • "product_id": 0,
  • "status": "string",
  • "status_display": "string",
  • "action": "string",
  • "action_display": "string",
  • "remote_id": "string",
  • "remote_status": "string",
  • "remote_status_display": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "campaign_budget": {
    },
  • "ads_account": {
    },
  • "google_ads_url": "http://example.com",
  • "google_ads_campaign_url": "http://example.com",
  • "negative_keywords_sync_enabled": true,
  • "has_active_adgroups": true,
  • "currency": {
    },
  • "internal_campaign_type": "SEARCH",
  • "clicks": 0,
  • "ctr": 0,
  • "cost": 0,
  • "conversions": 0,
  • "impressions": 0,
  • "remote_start_date": "2019-08-24",
  • "activate_retargeting_auto": true,
  • "landing_page_valid": true,
  • "keyword_clusters_ready": true,
  • "ads_created": true,
  • "campaign_published": true,
  • "location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "advertising_channel_type": "string",
  • "store_goals_enabled": true
}

Delete a campaign

Permanently deletes an outreach campaign and all associated opportunities, contacts, and scheduling data.

Authorizations:
apiKeyAuth

Responses

Get campaign sending settings

Returns the sending schedule settings for a campaign including daily limits, active days of the week, send time window, and counts of scheduled opportunities/contacts.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "campaign_budget": {
    },
  • "ads_account": {
    },
  • "location_criteria": [
    ],
  • "detailed_location_criteria": [
    ],
  • "excluded_location_criteria": [
    ],
  • "detailed_excluded_location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "radius_criteria": [
    ],
  • "google_ads_url": "http://example.com",
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0,
  • "location_targeting_type": "string"
}

Get per-campaign blacklist

Returns the domain/email blacklist specific to this campaign.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "blacklisted_domains": [
    ],
  • "blacklisted_emails": [
    ]
}

Update per-campaign blacklist

Replaces the domain/email blacklist for a specific campaign.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
blacklisted_domains
Array of strings

Full list of blacklisted domains (replaces existing)

blacklisted_emails
Array of strings

Full list of blacklisted email addresses

Responses

Request samples

Content type
application/json
{
  • "blacklisted_domains": [
    ],
  • "blacklisted_emails": [
    ]
}

Import opportunities from CSV

Imports outreach opportunities into a campaign from a CSV file upload. Each row should contain at minimum a domain/URL for the outreach target.

Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

CSV file with domain/URL and optional contact columns

Responses

Response samples

Content type
application/json
{
  • "imported_count": 0,
  • "skipped_count": 0
}

Update campaign sending settings

Updates the automated sending schedule for a campaign including daily limit, send time window (send_from / send_to hours), and active days of the week.

Authorizations:
apiKeyAuth
path Parameters
campaign
required
integer

Campaign ID

Request Body schema: application/json
required
name
string <= 255 characters
location_targeting_type
string
location_criteria
Array of strings

List of location criterion IDs or location objects with locationId and reach

language_criteria
Array of strings
bidding_strategy_type
string
target_cpa
number
max_cpc_bid
number
target_roas
number
amount_micros
integer

New budget amount

Responses

Request samples

Content type
application/json
{
  • "is_active": true,
  • "daily_limit": 20,
  • "send_from": "08:00",
  • "send_to": "18:00",
  • "days_of_week": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "campaign_budget": {
    },
  • "ads_account": {
    },
  • "location_criteria": [
    ],
  • "detailed_location_criteria": [
    ],
  • "excluded_location_criteria": [
    ],
  • "detailed_excluded_location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "radius_criteria": [
    ],
  • "google_ads_url": "http://example.com",
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0,
  • "location_targeting_type": "string"
}

Campaigns: Templates

Email templates for outreach campaigns

List email templates

Returns all email templates available for the authenticated customer's campaigns.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an email template

Creates a new reusable email template. Templates support variable substitution using {variable_name} syntax (e.g., {first_name}, {domain}, {keyword}).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string
subject
required
string
body
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Guest Post Pitch",
  • "subject": "Guest post opportunity for {domain}",
  • "body": "Hi {first_name},\n\nI'd love to contribute a guest post to your site..."
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "subject": "string",
  • "body": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "customer_id": 0
}

Update an email template

Updates an existing email template's name, subject, or body.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
template_id
required
integer
name
string
subject
string
body
string

Responses

Request samples

Content type
application/json
{
  • "template_id": 0,
  • "name": "string",
  • "subject": "string",
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "subject": "string",
  • "body": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "customer_id": 0
}

Delete an email template

Permanently removes an email template from the customer's template library.

Authorizations:
apiKeyAuth
query Parameters
template_id
required
integer

Template ID to delete

Responses

Campaigns: Opportunities

Manage outreach targets (websites to contact) within campaigns

Send bulk outreach emails for a campaign

Sends outreach emails to multiple scheduled opportunities in a campaign simultaneously. Requires a linked email, subject, and body template. Optional context variables are available for personalization (e.g., {first_name}, {domain}).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
opportunities
required
Array of integers

List of opportunity IDs to send to

linked_email_id
required
integer
subject
required
string
body
required
string
context
object
Default: {}

Responses

Request samples

Content type
application/json
{
  • "opportunities": [
    ],
  • "linked_email_id": 42,
  • "subject": "Link collaboration opportunity - {domain}",
  • "body": "Hi {first_name},\n\nI came across your site and thought we might collaborate...",
  • "context": { }
}

Schedule opportunities for outreach

Marks a set of opportunities as scheduled, adding them to the campaign's automated sending queue to be sent according to the campaign's schedule settings.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
opportunities
required
Array of integers

List of opportunity IDs

Responses

Request samples

Content type
application/json
{
  • "opportunities": [
    ]
}

List outreach opportunities

Returns outreach opportunities (discovered websites to contact) for a campaign. Each opportunity has contact data, domain metrics, and scheduling status.

Authorizations:
apiKeyAuth
query Parameters
campaign_id
required
integer

Campaign ID to list opportunities for

page
integer
Default: 1
page_size
integer
Default: 25
search
string
ordering
string
is_scheduled
boolean

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Send outreach email to a specific opportunity

Sends an outreach email to all contacts associated with a specific opportunity. Requires a linked email account, subject, and body. Supports variable substitution.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
linked_email_id
required
integer

ID of the linked email account to send from

subject
required
string

Email subject (supports {variable} substitution)

body
required
string

Email body (supports {variable} substitution)

context
object
Default: {}

Key-value pairs for variable substitution (e.g., {'custom_field': 'value'})

Responses

Request samples

Content type
application/json
{
  • "linked_email_id": 42,
  • "subject": "Collaboration opportunity",
  • "body": "Hi {first_name}, I wanted to reach out about a link exchange...",
  • "context": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email_sender": "user@example.com",
  • "email_to": "user@example.com",
  • "opportunity_details": {
    },
  • "thread": [
    ]
}

Delete an opportunity

Removes an outreach opportunity from a campaign. Any sent emails are preserved in the inbox.

Authorizations:
apiKeyAuth

Responses

Campaigns: Contacts

Contact management for outreach opportunities

Create a contact for an opportunity

Creates a new contact associated with an outreach opportunity. Contacts are the individual people at a website who will receive outreach emails.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
opportunity_id
required
integer
email_address
required
string <email>
first_name
string or null
last_name
string or null
title
string or null
photo_url
string or null
linkedin_url
string or null
twitter_url
string or null
github_url
string or null
facebook_url
string or null
website_url
string or null
file
string or null <binary>

Optional contact avatar/photo file upload

Responses

Request samples

Content type
application/json
{
  • "opportunity_id": 101,
  • "email_address": "editor@example.com",
  • "first_name": "Jane",
  • "last_name": "Smith",
  • "title": "Content Editor",
  • "linkedin_url": "https://linkedin.com/in/janesmith"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "opportunity_id": 0,
  • "email_address": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "title": "string",
  • "photo_url": "string",
  • "linkedin_url": "string",
  • "twitter_url": "string",
  • "github_url": "string",
  • "facebook_url": "string",
  • "website_url": "string"
}

Delete a contact

Removes a contact from an opportunity.

Authorizations:
apiKeyAuth

Responses

Bulk delete contacts

Deletes multiple contacts in a single request.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
contact_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "contact_ids": [
    ]
}

Campaigns: Inbox

Email inbox and thread management for outreach conversations

Update conversation milestone

Updates the relationship milestone for an outreach conversation. Milestones track the progress of a link building negotiation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
id
required
integer

Sent outreach email ID to update milestone for

milestone
required
string
Enum: "idle" "got_a_reply" "negotiation" "won" "lost"

Relationship stage in the link building negotiation:

  • idle: No reply yet / awaiting response
  • got_a_reply: Contact has replied
  • negotiation: Actively negotiating terms
  • won: Link placement confirmed
  • lost: Opportunity closed without placement

Responses

Request samples

Content type
application/json
{
  • "id": 55,
  • "milestone": "negotiation"
}

LLM Visibility: Overview

Track and analyze your brand's visibility across AI platforms including ChatGPT, Gemini, Perplexity, Copilot, Google AI Mode, and Grok. Monitor brand mentions, sentiment trends, competitor benchmarking, topic and query management, citation sources, and simulate AI prompts.

Base URL: https://llmvis.searchatlas.com

LLM Visibility: Projects

Brand visibility analysis projects. Each project links a user to a brand domain. Projects start as system projects (shared 30-day analysis) and can be converted to user-tracked projects for dedicated per-user analysis.

List LLM visibility projects

Returns all non-deleted LLM visibility projects for the authenticated user. Includes both system projects (is_user_tracked=false) and user-tracked projects.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a brand visibility project

Creates a new LLM visibility project for the given domain. If a brand for this domain already exists, it is reused. A system-level analysis snapshot is triggered automatically.

The project starts as a system project (is_user_tracked=false). Call POST /api/v1/projects/{projectId}/track/ to convert it to a user-tracked project.

QP integration: QP stores the returned project_id as Project.llmv_id.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
required
string <= 200 characters
description
string
is_active
boolean
Default: true
timezone
string

IANA timezone string (e.g. America/New_York)

object (PlatformsConfig)
default_approval_type
string
Enum: "AUTO_PUBLISH" "APPROVE_IF_IMAGE" "AI_IMAGES_ONLY" "APPROVE_FOR_PUBLISH"
default_image_source_type
string or null
object (AISettings)
image_prompt
string <= 1000 characters

Convenience alias - merged into ai_settings.image_prompt on save

Responses

Request samples

Content type
application/json
{
  • "domain": "searchatlas.com",
  • "country_code": "US",
  • "source": "api"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "success": true,
  • "status": "string",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9"
}

Get project details

Returns full project details for the authenticated user's project.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "timezone": "America/New_York",
  • "platforms_config": {
    },
  • "default_approval_type": "AUTO_PUBLISH",
  • "default_image_source_type": "string",
  • "ai_settings": {
    },
  • "image_prompt": "string",
  • "enabled_platforms": [
    ],
  • "posts_count": 0,
  • "schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete (untrack) a project

Soft-deletes the project and frees the quota slot. Equivalent to untracking - data is retained but the project is no longer active.

Authorizations:
apiKeyAuth

Responses

Convert project to user-tracked

Converts a system project to a user-tracked project. Validates quota availability, sets custom platforms and frequency, then triggers the first dedicated analysis run immediately.

When the credit system is enabled, frequency_days and selected_platforms can be provided. Otherwise, values are derived from the user's quota plan.

Authorizations:
apiKeyAuth
Request Body schema: application/json
optional
frequency_days
integer (FrequencyDaysEnum)
Enum: 1 3 7 14 30

Refresh frequency in days

selected_platforms
Array of strings (PlatformEnum)
Items Enum: "openai" "gemini" "perplexity" "copilot" "google_ai_mode" "grok"

Platforms to monitor. Must be subset of customer's allowed platforms.

Responses

Request samples

Content type
application/json
{
  • "frequency_days": 7,
  • "selected_platforms": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "success": true,
  • "status": "string",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9"
}

Untrack a user-tracked project

Converts a user-tracked project back to a system project. Frees the quota slot without deleting the project or its historical data. Distinct from DELETE /projects/{projectId}/.

Authorizations:
apiKeyAuth

Responses

Get project settings

Returns the current platform and frequency settings for a project.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "frequency_days": 1,
  • "selected_platforms": [
    ]
}

Update project settings

Updates the platform selection and/or refresh frequency for a user-tracked project. At least one field must be provided. Recalculates credit cost after update.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
frequency_days
integer (FrequencyDaysEnum)
Enum: 1 3 7 14 30

Refresh frequency in days

selected_platforms
Array of strings (PlatformEnum) non-empty
Items Enum: "openai" "gemini" "perplexity" "copilot" "google_ai_mode" "grok"

Responses

Request samples

Content type
application/json
{
  • "frequency_days": 1,
  • "selected_platforms": [
    ]
}

Response samples

Content type
application/json
{
  • "frequency_days": 1,
  • "selected_platforms": [
    ]
}

Update project refresh frequency

Updates only the refresh frequency for a user-tracked project.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
frequency_days
required
integer (FrequencyDaysEnum)
Enum: 1 3 7 14 30

Refresh frequency in days

Responses

Request samples

Content type
application/json
{
  • "frequency_days": 1
}

List project competitors

Returns all competitors discovered for this project's brand, with their selection status and source (auto-discovered or manually pinned).

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "competitors": [
    ]
}

Update competitor selections

Incrementally add/remove competitors from the deselected or pinned lists. Use add_deselected/remove_deselected to hide/show auto-discovered competitors. Use add_pinned/remove_pinned to manually pin specific competitor domains.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
add_deselected
Array of strings

Domains to hide from charts

remove_deselected
Array of strings

Domains to show in charts

add_pinned
Array of strings

Domains to manually pin as competitors

remove_pinned
Array of strings

Domains to unpin

Responses

Request samples

Content type
application/json
{
  • "add_deselected": [
    ],
  • "remove_deselected": [
    ],
  • "add_pinned": [
    ],
  • "remove_pinned": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": true,
  • "deselected_count": 0,
  • "pinned_count": 0
}

Trigger on-demand analysis

Triggers an immediate analysis run for the project using its configured platforms. Does not require a request body.

Authorizations:
apiKeyAuth
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "string",
  • "success": true,
  • "status": "string",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9"
}

Upload topics and queries via CSV

Uploads a CSV file to bulk-create topics and queries for the project's brand. CSV must have two columns: topic and query. Rows sharing the same topic value are grouped under the same topic (deduplicated). All created items have source=user_created.

CSV format:

topic,query
SEO Tools,What are the best SEO tools for small businesses?
SEO Tools,How to choose an SEO platform?
Authorizations:
apiKeyAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

CSV file with 'topic' and 'query' columns

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "topics_created": 0,
  • "queries_created": 0
}

Export topics and queries as CSV

Exports visibility data for topics and queries within the given time window as a CSV file. Supports platform and topic filtering.

Authorizations:
apiKeyAuth
Request Body schema: application/json
optional
from_date
string <date-time>

Inclusive start time. Overrides period if provided.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini')

topics
string

Comma-separated topic UUIDs

Responses

Request samples

Content type
application/json
{
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string"
}

Get credit usage history for a project

Returns the credit usage log entries for a specific project.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

LLM Visibility: Brand Visibility & Sentiment

Brand-level visibility metrics, trends, and sentiment analysis across LLM platforms. Includes overview data, visibility trends, sentiment trends, and topic/query breakdowns.

Get brand overview metrics

Returns aggregated brand visibility, sentiment, and citation metrics for a domain within the specified time window. Supports platform filtering, topic filtering, and sorting. Includes both current and previous period values for trend comparison.

Used by QP Report Builder.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

Responses

Request samples

Content type
application/json
{
  • "domain": "searchatlas.com",
  • "period": "30d",
  • "platforms": "openai,gemini"
}

Response samples

Content type
application/json
{
  • "domain": "string",
  • "filters": {
    },
  • "visibility": {
    },
  • "sentiment": {
    },
  • "citations": {
    }
}

Get brand visibility trend

Returns time-series visibility data for a brand across analysis snapshots. Each data point has a timestamp and per-platform visibility score values.

Used by QP Report Builder.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get brand sentiment trend

Returns time-series sentiment data for a brand across analysis snapshots. Each data point has a timestamp and per-platform sentiment score values.

Used by QP Report Builder.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

List available topics for a brand

Returns all active topics for a brand domain, for use in filter dropdowns. Supports partial-match search by title.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Brand domain (e.g., 'searchatlas.com')

search
string

Filter topics by title (case-insensitive partial match)

Responses

Response samples

Content type
application/json
{
  • "domain": "string",
  • "topics": [
    ]
}

List available queries for a brand

Returns all active queries for a brand domain with their parent topic context, for use in filter dropdowns. Supports partial-match search.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Brand domain (e.g., 'searchatlas.com')

search
string

Filter queries by title (case-insensitive partial match)

Responses

Response samples

Content type
application/json
{
  • "domain": "string",
  • "queries": [
    ]
}

Get sentiment overview by topic

Returns aggregated sentiment metrics grouped by topic. Includes average sentiment score, total mentions, and a list of up to 10 unique cited domains per topic.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

sentiment
string
Enum: "" "positive" "neutral" "negative"

Filter by sentiment category. Empty string = all.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "sentiment": ""
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get sentiment breakdown by query

Returns sentiment metrics grouped by individual query.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

sentiment
string
Enum: "" "positive" "neutral" "negative"

Filter by sentiment category. Empty string = all.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "sentiment": ""
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get topics grouped by sentiment category

Returns topics organized into three sentiment categories:

  • positive - all queries for this topic have positive sentiment
  • neutral - no negative queries, at least one neutral
  • negative - at least one query has negative sentiment
Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string"
}

Response samples

Content type
application/json
{
  • "positive": [
    ],
  • "neutral": [
    ],
  • "negative": [
    ]
}

Generate AI-powered summary

Generates a concise AI-powered summary (headline + insights + action) for a given domain and metrics dataset. Results are cached.

Summary types: overview, visibility_trend, sentiment, citations, competitors

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string

Domain being analyzed

summary_type
required
string
Enum: "overview" "visibility_trend" "sentiment" "citations" "competitors"

Type of summary to generate

required
object

Metrics data for analysis (structure varies by summary_type)

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "summary_type": "overview",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "headline": "string",
  • "insights": [
    ],
  • "action": "string",
  • "cached": true,
  • "summary_type": "string"
}

LLM Visibility: Competitor Benchmarking

Competitive analysis comparing brand visibility and share of voice against discovered competitors. Includes visibility rank, share of voice rank, visibility trends, and domain-level topic/query breakdowns.

Get topic-level metrics for a specific domain

Returns topic-level visibility and share of voice for any domain - brand or competitor. Useful for understanding which topics drive a domain's LLM presence.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

target_domain
required
string <= 255 characters

Domain to analyze (brand or competitor)

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "target_domain": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get query-level metrics for a specific domain

Returns query-level visibility and share of voice for any domain - brand or competitor. All queries returned are of type broad.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

target_domain
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "target_domain": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get competitor visibility rank

Returns a ranked list of competitor domains by average visibility score within the specified time window. Supports sorting and domain search.

Used by QP Report Builder.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

Responses

Request samples

Content type
application/json
{
  • "domain": "searchatlas.com",
  • "period": "30d",
  • "sort_by": "-visibility_score"
}

Response samples

Content type
application/json
{}

Get competitor share of voice rank

Returns a ranked list of competitor domains by average share of voice within the specified time window.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

Responses

Request samples

Content type
application/json
{
  • "domain": "searchatlas.com",
  • "period": "30d",
  • "sort_by": "-share_of_voice"
}

Response samples

Content type
application/json
{}

Get competitor visibility trend

Returns time-series visibility trend data for all selected competitor domains. Response is a map of domain_name → list of {timestamp, value} data points.

Used by QP Report Builder.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

LLM Visibility: Topics & Queries

Topic and query management for brand analysis. Topics represent research areas; queries are specific prompts sent to LLMs. Supports bulk creation, activation/deactivation, overview analytics, and trend analysis.

List topics for a brand

Returns topics for a brand domain with query count breakdown. Supports filtering by active/inactive status and title search.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Brand domain (e.g., 'searchatlas.com')

include_inactive
boolean
Default: false

Include inactive topics

search
string

Filter by topic title

page
integer
page_size
integer

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Bulk-create topics for a brand

Creates one or more user-created topics for a brand domain. Idempotent - existing topics with matching titles are reused.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string

Brand domain

required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "domain": "searchatlas.com",
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get topic-level visibility overview

Returns aggregated visibility metrics per topic for a brand domain. Includes rank, visibility score, share of voice, and search volume per topic. Supports time-window, platform, and query_type filtering.

Used by QP Report Builder.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

query_type
string
Enum: "branded" "broad"

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "query_type": "branded"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

List unanalyzed topics

Returns topics that have not yet been included in any analysis snapshot.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string
topics
Array of strings <uuid> [ items <uuid > ]
search
string

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "topics": [
    ],
  • "search": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get topic details

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "source": "auto_generated",
  • "is_active": true,
  • "query_count": {
    }
}

Update topic title

Updates the display title of an existing topic.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
title
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "source": "auto_generated",
  • "is_active": true,
  • "query_count": {
    }
}

Delete a topic

Soft-deletes the topic and all its associated queries.

Authorizations:
apiKeyAuth

Responses

Deactivate a topic

Deactivates the topic for the current user. Deactivated topics are excluded from analysis and metrics. The topic remains visible to other users.

Authorizations:
apiKeyAuth

Responses

Reactivate a topic

Re-includes a previously deactivated topic in analysis and metrics.

Authorizations:
apiKeyAuth

Responses

List queries for a brand

Returns queries for a brand domain with topic context. Supports filtering by topic_id, active/inactive status, and title search.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Brand domain

topic_id
string <uuid>

Filter queries by topic UUID

include_inactive
boolean
Default: false
page
integer
page_size
integer

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Bulk-create queries under a topic

Creates one or more user-created queries under a specific topic. Idempotent - existing queries with matching titles under the same topic are reused.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string
topic_id
required
string <uuid>
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "domain": "searchatlas.com",
  • "topic_id": "550e8400-e29b-41d4-a716-446655440000",
  • "queries": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get query-level visibility overview

Returns aggregated visibility metrics per query for a brand domain. Includes rank, visibility score, share of voice, search volume, and query type.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

query_type
string
Enum: "branded" "broad"

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "query_type": "branded"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get available snapshot dates for a query

Returns all analysis snapshots where the given query was successfully processed. Use to populate date selectors in trend/comparison UIs.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "query_id": "6fa29c22-6bab-424a-859e-a13a5c607e72"
}

Response samples

Content type
application/json
{
  • "query_id": "6fa29c22-6bab-424a-859e-a13a5c607e72",
  • "available_dates": [
    ]
}

Get visibility trend for a query

Returns time-series visibility data for a specific query across snapshots. Each point has a timestamp and per-platform visibility score values.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query
required
string <uuid>

Query UUID

from_date
string <date-time>
to_date
string <date-time>
period
string
Enum: "7d" "30d" "90d"
platforms
string

Comma-separated platform keys

Responses

Request samples

Content type
application/json
{
  • "query": "f3c5bd2e-6d34-4350-ae9d-95c2f071389c",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get share of voice trend for a query

Returns time-series share of voice data for a specific query across snapshots.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query
required
string <uuid>

Query UUID

from_date
string <date-time>
to_date
string <date-time>
period
string
Enum: "7d" "30d" "90d"
platforms
string

Comma-separated platform keys

Responses

Request samples

Content type
application/json
{
  • "query": "f3c5bd2e-6d34-4350-ae9d-95c2f071389c",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get citation trend for a query

Returns time-series citation data (mention counts) for a specific query across snapshots.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query
required
string <uuid>

Query UUID

from_date
string <date-time>
to_date
string <date-time>
period
string
Enum: "7d" "30d" "90d"
platforms
string

Comma-separated platform keys

Responses

Request samples

Content type
application/json
{
  • "query": "f3c5bd2e-6d34-4350-ae9d-95c2f071389c",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

List unanalyzed queries

Returns queries that have not yet been included in any analysis snapshot.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string
topics
Array of strings <uuid> [ items <uuid > ]
search
string

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "topics": [
    ],
  • "search": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get query details

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
  • "topic_title": "string",
  • "title": "string",
  • "query_type": "branded",
  • "source": "auto_generated",
  • "is_active": true
}

Update query title

Updates the display title of an existing query.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
title
required
string

Responses

Request samples

Content type
application/json
{
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
  • "topic_title": "string",
  • "title": "string",
  • "query_type": "branded",
  • "source": "auto_generated",
  • "is_active": true
}

Delete a query

Soft-deletes the query.

Authorizations:
apiKeyAuth

Responses

Deactivate a query

Deactivates the query for the current user, excluding it from analysis.

Authorizations:
apiKeyAuth

Responses

Reactivate a query

Authorizations:
apiKeyAuth

Responses

Retrieve raw LLM responses for a query

Returns raw LLM platform responses for a specific query within a snapshot. Supports optional platform filtering.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query_id
required
string <uuid>

Query UUID to retrieve responses for

snapshot_id
required
string <uuid>

Snapshot UUID containing the responses

platforms
string

Optional comma-separated platform list (e.g., 'openai,gemini')

Responses

Request samples

Content type
application/json
{
  • "query_id": "6fa29c22-6bab-424a-859e-a13a5c607e72",
  • "snapshot_id": "163831af-8c1b-4992-a9cf-88c6306604c0",
  • "platforms": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

LLM Visibility: Citations & Sources

Citation analysis showing which URLs and domains LLMs cite when answering brand-related queries. Includes domain-level, URL-level, platform-level, topic-level, and query-level citation breakdowns.

Get citations for a specific query

Returns cited URLs/domains for a specific query within the analysis window.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query
required
string <uuid>

Query UUID

from_date
string <date-time>
to_date
string <date-time>
period
string
Enum: "7d" "30d" "90d"
platforms
string

Comma-separated platform keys

Responses

Request samples

Content type
application/json
{
  • "query": "f3c5bd2e-6d34-4350-ae9d-95c2f071389c",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string"
}

Response samples

Content type
application/json
{}

Get citation domain overview

Returns a ranked list of domains cited by LLMs when answering brand-related queries. Includes total mention counts and share of voice per cited domain.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

citation_domain
string <= 255 characters

Filter citations for a specific domain only

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "citation_domain": "string"
}

Response samples

Content type
application/json
{}

Get citation share by platform

Returns the percentage share of citations per LLM platform within the filtered window. Response is a map of platform key → mention share percentage.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

citation_domain
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "citation_domain": "string"
}

Response samples

Content type
application/json
{
  • "values": {
    }
}

Get citation breakdown by topic

Returns citation mention counts and share of voice grouped by topic.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

citation_domain
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "citation_domain": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get citation breakdown by query

Returns citation mention counts and share of voice grouped by query.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

citation_domain
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "citation_domain": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get citation URL breakdown

Returns individual URL-level citation metrics including domain, mention count, share of voice, citation score, average rank, and platforms that cited each URL.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

citation_domain
string <= 255 characters
citation_url
string <= 2048 characters

Exact URL to filter for

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "citation_domain": "string",
  • "citation_url": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get query-to-URL citation mapping

Returns which queries led to which URL citations. Enables Query → URL → Citation drilldown analysis.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

citation_domain
string <= 255 characters
citation_url
string <= 2048 characters

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "citation_domain": "string",
  • "citation_url": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get per-platform URL citation breakdown

Returns citation performance for each URL broken down by LLM platform. Useful for understanding which platforms cite specific URLs.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
domain
required
string <= 255 characters

Brand domain to analyze

from_date
string <date-time>

Inclusive start time. Overrides period.

to_date
string <date-time>

Exclusive end time. Defaults to now.

period
string
Enum: "7d" "30d" "90d"

Quick period selector. Ignored if from_date provided.

platforms
string

Comma-separated platform keys (e.g., 'openai,gemini'). Default: all.

topics
string

Comma-separated topic UUIDs. Default: all topics.

queries
string

Comma-separated query UUIDs. Default: all queries.

sort_by
string

Sort field. Prefix with '-' for descending.

search
string

Search term for title-based filtering.

citation_domain
string <= 255 characters
citation_url
string <= 2048 characters

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "from_date": "2019-08-24T14:15:22Z",
  • "to_date": "2019-08-24T14:15:22Z",
  • "period": "7d",
  • "platforms": "string",
  • "topics": "string",
  • "queries": "string",
  • "sort_by": "string",
  • "search": "string",
  • "citation_domain": "string",
  • "citation_url": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

LLM Visibility: Prompt Simulation

On-demand prompt testing - submit arbitrary prompts to multiple LLM platforms and get structured analysis including brand mentions, citations, sentiment, and competitor visibility.

List prompt analyses

Returns all prompt analysis submissions for the authenticated user, ordered by most recent.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Submit prompts for analysis

Submits 1-100 prompts for execution across the specified LLM platforms. Analysis runs asynchronously via BrightData integration. Poll the check-status endpoint to track completion.

No quota restrictions - PS runs independently of project quota.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
prompts
required
Array of strings [ 1 .. 100 ] items [ items <= 5000 characters ]

List of prompt texts to execute

platforms
required
Array of strings (PlatformEnum) non-empty
Items Enum: "openai" "gemini" "perplexity" "copilot" "google_ai_mode" "grok"

Platforms to execute prompts on (no duplicates)

country_code
string <= 2 characters
Default: "US"

ISO 3166-1 alpha-2 country code. Defaults to 'US'.

target_domain
string or null <= 255 characters

Optional target domain for comparison mode

Responses

Request samples

Content type
application/json
{
  • "prompts": [
    ],
  • "platforms": [
    ],
  • "country_code": "US",
  • "target_domain": "searchatlas.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "platforms": [
    ],
  • "country_code": "string",
  • "prompts_count": 0,
  • "responses_count": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "target_domain": "string"
}

Check analysis status

Returns the current status of one or more prompt analysis submissions.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
analysis_ids
required
Array of strings <uuid> [ items <uuid > ]

List of analysis IDs to check

Responses

Request samples

Content type
application/json
{
  • "analysis_ids": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get prompt submission history

Returns a flat list of individual prompt submissions with their analysis context.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get prompt analysis detail

Returns full analysis detail including all prompts and their raw LLM responses.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "platforms": [
    ],
  • "country_code": "string",
  • "prompts_count": 0,
  • "responses_count": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "target_domain": "string",
  • "error_message": "string",
  • "prompts": [
    ]
}

Get model responses for an analysis

Returns individual LLM response items with brand mention metrics, citations, and competitor brands for each response.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get analysis summary metrics

Returns aggregated summary metrics for the analysis including total platforms, brand mention rate, share of voice, average position, top competitors, and most cited domains.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "total_platforms": 0,
  • "mentioned_platforms": 0,
  • "share_of_voice": 0.1,
  • "average_position": 0.1,
  • "top_competitors": [
    ],
  • "common_citations": [
    ]
}

Get competitor visibility chart data

Returns competitor visibility scores for bar chart display, comparing the target brand against discovered competitors across all responses.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

LLM Visibility: Credits

Credit balance management for the credit-based quota system. 1 credit = 1 query × 1 platform × 1 refresh.

Get credit usage history for a project

Returns the credit usage log entries for a specific project.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get credit balance summary

Returns the customer's overall credit balance including:

  • Monthly allocation (credits from plan)
  • Purchased credits (top-ups)
  • Remaining balance for each pool
  • Combined total remaining
Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "monthly_total": 0,
  • "monthly_consumed": 0,
  • "monthly_remaining": 0,
  • "purchased_total": 0,
  • "purchased_consumed": 0,
  • "purchased_remaining": 0,
  • "total_remaining": 0,
  • "credit_system_enabled": true
}

Estimate credit cost for a configuration

Estimates the credit impact for a given configuration without consuming any credits. Use this before tracking a project to show users the expected monthly cost.

Formula: credits_per_run = query_count × platform_count Monthly estimate: credits_per_run × (30 / frequency_days)

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
query_count
required
integer >= 0

Number of active queries

platform_count
required
integer [ 1 .. 6 ]

Number of selected platforms

frequency_days
required
integer (FrequencyDaysEnum)
Enum: 1 3 7 14 30

Refresh frequency in days

Responses

Request samples

Content type
application/json
{
  • "query_count": 20,
  • "platform_count": 3,
  • "frequency_days": 7
}

Response samples

Content type
application/json
{
  • "credits_per_run": 0,
  • "refreshes_per_month": 0,
  • "estimated_monthly_credits": 0,
  • "query_count": 0,
  • "platform_count": 0,
  • "frequency_days": 0
}

Get projected monthly credit usage

Returns the total projected monthly credit usage across all user-tracked projects. Includes per-project breakdown showing cost per run, frequency, and monthly estimate.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "total_projected_monthly_credits": 0,
  • "project_count": 0,
  • "projects": [
    ]
}

LLM Visibility: Platforms

Platform availability status and degradation notifications.

List all platform statuses

Returns the current operational status for all supported LLM platforms.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get platform status by ID

Authorizations:
apiKeyAuth
path Parameters
id
required
integer

Platform record ID

Responses

Response samples

Content type
application/json
{
  • "platform": "openai",
  • "is_enabled": true,
  • "status": "active"
}

Get platform degradation notifications

Returns notification data for platforms currently in a degraded or disabled state. Used to surface banners/warnings in the UI.

Note: The camelCase URL is preserved for backward compatibility.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get platforms for a domain's project

Returns the list of platforms configured for an existing project associated with the given domain. Used by QP Report Builder to populate platform filters.

QP integration: Called by QP Report Builder before generating reports.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Domain to get project platforms for (e.g., 'searchatlas.com')

Responses

Response samples

Content type
application/json
{
  • "platforms": [
    ]
}

LLM Visibility: SE (Site Explorer)

Site Explorer integration endpoints - visibility overview, LLM visibility table, sentiment table, analysis status, and query response detail.

Get domain visibility overview (SE)

Returns high-level visibility metrics for a domain from the latest successful analysis. Aggregates topic coverage, brand presence, and sentiment across platforms.

Used by the Site Explorer module. Supports public access via share hash.

QP integration: Used by QP for homepage dashboard brand mentions.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{
  • "domain": "string",
  • "platforms": [
    ],
  • "project_public_hash": "6caac543-81cf-491f-a6ae-ecbef367d59c"
}

Get LLM visibility table (SE)

Returns a table of topic/query pairs with visibility scores, brand rank, citation share of voice, and potential search volume. Used to power the main LLM visibility table in Site Explorer.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string
platform
string
Enum: "openai" "gemini" "perplexity" "copilot" "google_ai_mode" "grok"

Optional platform filter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get sentiment table (SE)

Returns a table of topic/query pairs with sentiment scores for the domain. Supports platform and sentiment category filtering.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string
platform
string
Enum: "openai" "gemini" "perplexity" "copilot" "google_ai_mode" "grok"
sentiment
string
Enum: "" "positive" "neutral" "negative"

Filter by sentiment category

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get analysis status for a domain (SE)

Returns the current analysis status for a domain. Includes snapshot ID, project ID, platform completion tracking, and any in-progress analysis info. Used to poll for analysis readiness and display progress indicators.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{
  • "domain": "string",
  • "status": "pending",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "snapshot_id": "163831af-8c1b-4992-a9cf-88c6306604c0",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "completed_platforms": [
    ],
  • "pending_platforms": [
    ],
  • "total_platforms": 0,
  • "latest_analysis": {
    }
}

Get raw LLM response for a query (SE)

Returns the raw LLM response body for a specific domain, platform, and query.

Authorizations:
apiKeyAuth
query Parameters
domain
required
string
platform
required
string
Enum: "openai" "gemini" "perplexity" "copilot" "google_ai_mode" "grok"
query_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "body": "string",
  • "snapshot_date": "2019-08-24",
  • "top_competitors": [
    ],
  • "target_brand_domain": "string"
}

Otto PPC: Overview

Google Ads campaign management and automation platform. Connect Google Ads accounts, manage business profiles, create and optimize campaigns with AI-generated keywords and ad copy, run PPC audits across 5 pillars (campaign efficiency, keyword performance, creative quality, account health, spend efficiency), and manage retargeting audiences.

Base URL: https://otto-ppc.searchatlas.com

Otto PPC: Ads Accounts

Manage connected Google Ads accounts and retrieve account-level metadata

List Google Ads accounts

Returns all active Google Ads accounts associated with the authenticated user's customer account. Accounts must have a name and be marked active.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Google Ads accounts grouped by user email

Syncs the local database with the Google Search Console (GSC) first, then returns all Google Ads accounts grouped by the user's Google email address. Includes internal selection/active status and credential metadata.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Otto PPC: Business Profiles

Create and manage business profiles that anchor PPC campaigns

List business profiles

Returns all business profiles for the authenticated user's account, annotated with campaign counts, retargeting status, and currency info. Supports search by name, ordering, and campaign-type filtering.

Authorizations:
apiKeyAuth
query Parameters
search
string

Filter by business name

ordering
string

Field to order results by. Prefix with - for descending.

status
string

Filter by business status

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a business profile

Creates a new business profile linked to a Google Ads account. Triggers asynchronous background jobs to process industries, phone numbers, and competitors.

If import_campaign=true, the business is created in importing state. If brand_vault_uuid is provided, brand strategy fields are synced from Brand Vault.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string or null <= 255 characters

Business name. Defaults to website_url if not provided.

website_url
string <= 2048 characters
description
string or null
google_ads_account
required
integer

Required - ID of the connected AdsAccount

Array of objects (LocationEntry) <= 100 items
revenue_model
string or null
brand_identity
string or null
value_proposition
string or null
specific_landing_page
string or null
target_language
string or null

Google Ads language criterion ID

internal_campaigns_type
Array of strings
Items Enum: "SEARCH" "IMPORTED"
enable_local_keywords
boolean
Default: false
brand_vault_uuid
string or null <uuid>

Link to Brand Vault profile (cannot be changed after creation)

import_campaign
boolean
Default: false

Set true to start the business in campaign-import mode

confirm_vault_write_back
boolean
Default: false

If true, writes brand strategy fields back to Brand Vault

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Corp",
  • "website_url": "https://acmecorp.com",
  • "google_ads_account": 42,
  • "description": "B2B SaaS for project management",
  • "revenue_model": "Subscription",
  • "brand_identity": "Professional and approachable",
  • "value_proposition": "Save 10 hours a week on reporting",
  • "location_data": [
    ],
  • "target_language": "1000",
  • "internal_campaigns_type": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "website_url": "http://example.com",
  • "status": "string",
  • "common_status": "string",
  • "last_operation_timestamp": 0,
  • "google_ads_account": 0,
  • "published_ads_count": 0,
  • "target_language": "string",
  • "currency": {
    },
  • "internal_campaigns_type": [
    ],
  • "show_activation_modal": true,
  • "all_products_retargeted": true,
  • "created_campaigns_count": 0,
  • "has_active_campaign": true,
  • "active_campaign_count": 0,
  • "description": "string",
  • "revenue_model": "string",
  • "brand_identity": "string",
  • "value_proposition": "string",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "location_data": [
    ],
  • "specific_landing_page": "string",
  • "enable_local_keywords": false
}

List business profiles (v2)

V2 version of the business list endpoint with extended product data.

Authorizations:
apiKeyAuth
query Parameters
search
string
ordering
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a business profile

Returns the full details of a single business profile including campaign metadata.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "website_url": "http://example.com",
  • "status": "string",
  • "common_status": "string",
  • "last_operation_timestamp": 0,
  • "google_ads_account": 0,
  • "published_ads_count": 0,
  • "target_language": "string",
  • "currency": {
    },
  • "internal_campaigns_type": [
    ],
  • "show_activation_modal": true,
  • "all_products_retargeted": true,
  • "created_campaigns_count": 0,
  • "has_active_campaign": true,
  • "active_campaign_count": 0,
  • "description": "string",
  • "revenue_model": "string",
  • "brand_identity": "string",
  • "value_proposition": "string",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "location_data": [
    ],
  • "specific_landing_page": "string",
  • "enable_local_keywords": false
}

Update a business profile

Partially updates a business profile. Location data changes trigger automatic re-sync of local keyword geo-variants when enabled.

Note: internal_campaigns_type and brand_vault_uuid cannot be updated after creation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string <= 255 characters
website_url
string <= 2048 characters
description
string
Array of objects (LocationEntry) <= 100 items
revenue_model
string
brand_identity
string
value_proposition
string
specific_landing_page
string
target_language
string
enable_local_keywords
boolean
import_campaign
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "website_url": "string",
  • "description": "string",
  • "location_data": [
    ],
  • "revenue_model": "string",
  • "brand_identity": "string",
  • "value_proposition": "string",
  • "specific_landing_page": "string",
  • "target_language": "string",
  • "enable_local_keywords": true,
  • "import_campaign": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "website_url": "http://example.com",
  • "status": "string",
  • "common_status": "string",
  • "last_operation_timestamp": 0,
  • "google_ads_account": 0,
  • "published_ads_count": 0,
  • "target_language": "string",
  • "currency": {
    },
  • "internal_campaigns_type": [
    ],
  • "show_activation_modal": true,
  • "all_products_retargeted": true,
  • "created_campaigns_count": 0,
  • "has_active_campaign": true,
  • "active_campaign_count": 0,
  • "description": "string",
  • "revenue_model": "string",
  • "brand_identity": "string",
  • "value_proposition": "string",
  • "brand_vault_uuid": "ed6573dc-c380-4a19-bc05-007c933224bc",
  • "location_data": [
    ],
  • "specific_landing_page": "string",
  • "enable_local_keywords": false
}

Delete a business profile

Soft-deletes the business profile and all associated campaigns and products.

Authorizations:
apiKeyAuth

Responses

Discover new products for a business (async)

Triggers an asynchronous crawl of the business website to discover new products or services that can be turned into ad campaigns. Returns a task ID to poll.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Otto PPC: Products

Products are the campaign-level units within a business - each product maps to a Google Ads campaign

List products

Returns products for the authenticated user's account with campaign performance metrics. Filterable by business_id, campaign_id, product_id, is_approved, and internal_campaign_type. Supports search and ordering.

Authorizations:
apiKeyAuth
query Parameters
business_id
integer

Filter by business ID

is_approved
boolean

Filter by approval status

campaign_id
integer
product_id
integer
internal_campaign_type
string
Enum: "SEARCH" "RETARGETED"
product_ids
string

Comma-separated list of product IDs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List products (v2)

V2 version of the products list with extended keyword cluster and performance data.

Authorizations:
apiKeyAuth
query Parameters
business_id
integer
is_approved
boolean
campaign_id
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a product to a business

Creates a new product (and its associated campaign) for a given business. If a product with the same slugified name already exists, it is updated instead. Automatically assigns a category of "Service" if none is provided.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
business_id
required
integer
name
required
string
landing_page
required
string <uri>
description
required
string
category
string

Defaults to "Service" if not provided

unique_selling_points
Array of strings
Default: []
include_free_or_cheap_words
boolean
Default: false
include_competitors_names
boolean
Default: false
landing_page_valid
boolean
Default: false
validation_error
string

Responses

Request samples

Content type
application/json
{
  • "business_id": 12,
  • "name": "Project Management Software",
  • "landing_page": "https://acmecorp.com/product/pm",
  • "description": "Cloud-based project management tool for teams",
  • "category": "Software",
  • "unique_selling_points": [
    ],
  • "include_free_or_cheap_words": false,
  • "include_competitors_names": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "string",
  • "name": "string",
  • "category": "string",
  • "landing_page": "http://example.com",
  • "description": "string",
  • "unique_selling_points": [
    ],
  • "include_free_or_cheap_words": true,
  • "is_branded": true,
  • "include_competitors_names": true,
  • "task_status": "string",
  • "task_status_display": "string",
  • "task_process_started_at": "2019-08-24T14:15:22Z",
  • "task_process_ended_at": "2019-08-24T14:15:22Z"
}

Create products for a business

Triggers AI-powered generation of product definitions for the given business. Products are generated from the business website content. Returns a task ID.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Bulk add products to a business

Adds multiple products to a business in a single request. Useful for importing product catalogs or adding multiple pages at once.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
Array of objects (ProductCreateRequest)

Responses

Request samples

Content type
application/json
{
  • "products": [
    ]
}

Update a product

Partially updates a product's name, landing page, description, USPs, and targeting settings.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string
landing_page
string <uri>
description
string
category
string
unique_selling_points
Array of strings
include_free_or_cheap_words
boolean
include_competitors_names
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "landing_page": "http://example.com",
  • "description": "string",
  • "category": "string",
  • "unique_selling_points": [
    ],
  • "include_free_or_cheap_words": true,
  • "include_competitors_names": true
}

Response samples

Content type
application/json
{
  • "product_id": 0,
  • "product_name": "string",
  • "is_approved": true,
  • "common_status": "string",
  • "logo": "http://example.com",
  • "is_branded": true,
  • "campaign_id": 0,
  • "campaign_name": "string",
  • "remote_id": "string",
  • "remote_status": "ENABLED",
  • "campaign_sync_status": "string",
  • "campaign_sync_error_msg": "string",
  • "campaign_type": "Search Campaign",
  • "last_operation_timestamp": 0,
  • "ads_count": 0,
  • "ads_groups_count": 0,
  • "campaign_budget": {
    },
  • "business": 0,
  • "category": "string",
  • "landing_page": "http://example.com",
  • "original_landing_page": "http://example.com",
  • "description": "string",
  • "unique_selling_points": [
    ],
  • "include_free_or_cheap_words": true,
  • "include_competitors_names": true,
  • "landing_page_valid": true,
  • "validation_error": "string",
  • "has_ai_landing_page_active": true,
  • "approved_ads_count": 0,
  • "approved_ad_groups_count": 0,
  • "negative_keywords_sync_enabled": true,
  • "negative_keyword_count": 0,
  • "negative_keywords_last_synced_date": "2019-08-24T14:15:22Z",
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0,
  • "clicks": 0,
  • "conversions": 0,
  • "cost": 0,
  • "ctr": 0,
  • "location_fraction": 0
}

Update product remote (Google Ads) status

Toggles the remote status of a product's campaign on Google Ads (e.g. enable/pause). Optionally propagates the status change to related ad groups and ads.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
task_status
required
string
Enum: "READY" "ACTIVE" "READY_NOT_ACTIVE" "PAUSED" "ENABLED"

Maps to Google Ads remote status:

  • ACTIVE / ENABLED → ENABLED
  • READY / READY_NOT_ACTIVE / PAUSED → PAUSED
include_related
boolean
Default: true

When true, propagates the status change to related ad groups and ads

Responses

Request samples

Content type
application/json
{
  • "task_status": "READY",
  • "include_related": true
}

Bulk update product remote statuses

Enables or pauses multiple products' Google Ads campaigns in one call.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
product_ids
required
Array of integers
task_status
required
string
Enum: "ENABLED" "PAUSED"
include_related
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ],
  • "task_status": "ENABLED",
  • "include_related": true
}

Approve a product

Marks a product as approved, making it eligible for campaign publishing.

Authorizations:
apiKeyAuth

Responses

Disapprove a product

Reverts a product from approved status back to pending, preventing publishing.

Authorizations:
apiKeyAuth

Responses

Bulk approve products

Approves multiple products in a single operation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
product_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Bulk disapprove products

Disapproves multiple products in a single operation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
product_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Delete a product

Soft-deletes (marks as removed) a product and its campaign. Use delete_from_google=true to also remove the campaign from Google Ads. Use delete_retargeting_campaign=true to remove any associated retargeting campaign.

Authorizations:
apiKeyAuth
query Parameters
delete_from_google
boolean
Default: false
delete_retargeting_campaign
boolean
Default: false

Responses

Bulk delete products

Soft-deletes multiple products and their campaigns in one call.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
product_ids
required
Array of integers
delete_from_google
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ],
  • "delete_from_google": false
}

Restore a deleted product

Restores a previously soft-deleted product back to pending status.

Authorizations:
apiKeyAuth

Responses

Get products with grouped keyword clusters

Returns products with their keyword clusters nested under each product. Used for the grouped keyword view in the UI. Supports filtering by business_id, search_intent, match_type, and approval status.

Authorizations:
apiKeyAuth
query Parameters
business_id
required
integer
ordering
string

Order clusters by: relevancy_score, sv_total, cpc_avg, cmp_avg

search_intent
string
match_type
string
Enum: "BROAD" "PHRASE" "EXACT"
approval_status
string
Enum: "approved" "non_approved"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Otto PPC: Campaigns & Budgets

Campaign configuration, budget creation, bulk publishing, and settings management

List campaigns

Returns all campaigns for the authenticated user's account. Filterable by business_id, ads_account_id, and internal_campaign_type.

Authorizations:
apiKeyAuth
query Parameters
business_id
integer
ads_account_id
integer
internal_campaign_type
string
Enum: "SEARCH" "RETARGETED"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a campaign

Partially updates campaign fields such as name, remote_status, negative_keywords_sync_enabled, and bidding strategy fields.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string <= 255 characters
remote_status
string
Enum: "ENABLED" "PAUSED"
negative_keywords_sync_enabled
boolean
bidding_strategy_type
string
target_cpa
number
max_cpc_bid
number
target_roas
number

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "remote_status": "ENABLED",
  • "negative_keywords_sync_enabled": true,
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "business_id": 0,
  • "product_id": 0,
  • "status": "string",
  • "status_display": "string",
  • "action": "string",
  • "action_display": "string",
  • "remote_id": "string",
  • "remote_status": "string",
  • "remote_status_display": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "campaign_budget": {
    },
  • "ads_account": {
    },
  • "google_ads_url": "http://example.com",
  • "google_ads_campaign_url": "http://example.com",
  • "negative_keywords_sync_enabled": true,
  • "has_active_adgroups": true,
  • "currency": {
    },
  • "internal_campaign_type": "SEARCH",
  • "clicks": 0,
  • "ctr": 0,
  • "cost": 0,
  • "conversions": 0,
  • "impressions": 0,
  • "remote_start_date": "2019-08-24",
  • "activate_retargeting_auto": true,
  • "landing_page_valid": true,
  • "keyword_clusters_ready": true,
  • "ads_created": true,
  • "campaign_published": true,
  • "location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "advertising_channel_type": "string",
  • "store_goals_enabled": true
}

Get campaign settings

Returns detailed campaign settings including location targeting, language criteria, budget, bidding strategy, and Google Ads URLs. Used in the campaign settings drawer.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "campaign_budget": {
    },
  • "ads_account": {
    },
  • "location_criteria": [
    ],
  • "detailed_location_criteria": [
    ],
  • "excluded_location_criteria": [
    ],
  • "detailed_excluded_location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "radius_criteria": [
    ],
  • "google_ads_url": "http://example.com",
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0,
  • "location_targeting_type": "string"
}

Update campaign settings

Updates campaign settings from the settings drawer, including name, location targeting, language criteria, bidding strategy, and budget amount.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
name
string <= 255 characters
location_targeting_type
string
location_criteria
Array of strings

List of location criterion IDs or location objects with locationId and reach

language_criteria
Array of strings
bidding_strategy_type
string
target_cpa
number
max_cpc_bid
number
target_roas
number
amount_micros
integer

New budget amount

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "location_targeting_type": "string",
  • "location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0,
  • "amount_micros": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "campaign_budget": {
    },
  • "ads_account": {
    },
  • "location_criteria": [
    ],
  • "detailed_location_criteria": [
    ],
  • "excluded_location_criteria": [
    ],
  • "detailed_excluded_location_criteria": [
    ],
  • "language_criteria": [
    ],
  • "radius_criteria": [
    ],
  • "google_ads_url": "http://example.com",
  • "bidding_strategy_type": "string",
  • "target_cpa": 0,
  • "max_cpc_bid": 0,
  • "target_roas": 0,
  • "location_targeting_type": "string"
}

Create a campaign budget for a product

Creates or updates the campaign budget for the specified product. The budget amount is specified in the account's currency. Validates that the amount is greater than 0.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
amount_micros
required
integer

Daily budget in the account's base currency unit (must be > 0)

delivery_method
string
Default: "STANDARD"
Enum: "STANDARD" "ACCELERATED"

Responses

Request samples

Content type
application/json
{
  • "amount_micros": 50,
  • "delivery_method": "STANDARD"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "amount_micros": 0,
  • "delivery_method": "STANDARD",
  • "status": "string",
  • "action": "string",
  • "remote_id": "string",
  • "remote_status": "string",
  • "error_message": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Bulk create campaign budgets

Creates or updates campaign budgets for multiple products in a single request.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
product_ids
required
Array of integers
amount_micros
required
integer

Daily budget amount in the account's base currency unit (not micros despite the name)

delivery_method
string
Default: "STANDARD"
Enum: "STANDARD" "ACCELERATED"

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ],
  • "amount_micros": 0,
  • "delivery_method": "STANDARD"
}

Bulk send campaigns to Google Ads

Publishes multiple approved campaigns to Google Ads in a single operation. Campaigns must have a valid budget and approved keywords/ads before sending. Returns a task ID for async polling.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
campaign_ids
required
Array of integers

List of campaign IDs to publish

Responses

Request samples

Content type
application/json
{
  • "campaign_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Import Google Ads campaigns

Imports existing campaigns from a connected Google Ads account into OTTO PPC. Triggers a sync from the Google Ads account to populate campaigns, ad groups, keywords, and ads into the local database.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
ads_account_id
required
integer
business_id
integer or null
campaign_ids
Array of strings

Optional list of specific Google Ads campaign remote IDs to import

Responses

Request samples

Content type
application/json
{
  • "ads_account_id": 0,
  • "business_id": 0,
  • "campaign_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Bulk toggle negative keywords sync

Enables or disables automatic negative keyword syncing for multiple campaigns. When enabled, search term waste data is periodically analyzed to add negative keywords automatically.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
enabled
required
boolean

True to enable negative keywords sync, false to disable

campaign_ids
required
Array of integers non-empty

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "campaign_ids": [
    ]
}

Otto PPC: Keywords & Targeting

Keyword clusters (ProductTargetKeywords), ad-group generation, and keyword operations

List keyword clusters

Returns keyword clusters (ProductTargetKeywords) for the authenticated user's account. Each cluster maps to one ad group and contains target exact, phrase, and negative keywords with SEO metrics (search volume, CPC, competition). Filterable by business, campaign, or product.

Authorizations:
apiKeyAuth
query Parameters
business_id
integer
campaign_id
integer
product_id
integer
is_approved
boolean
search_intent
string
match_type
string
Enum: "BROAD" "PHRASE" "EXACT"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a keyword cluster

Updates the keywords in a cluster. If target_exact_keywords is set to empty, the cluster is marked as removed. Supports match type changes which trigger an async Google Ads sync.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
target_exact_keywords
object or null

Dict of keyword → metrics. Setting to empty/null marks cluster as removed.

match_type
string
Enum: "BROAD" "PHRASE" "EXACT"

Responses

Request samples

Content type
application/json
{
  • "target_exact_keywords": { },
  • "match_type": "BROAD"
}

Update keyword cluster remote status

Enables or pauses the ad group associated with this keyword cluster on Google Ads.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
task_status
required
string
Enum: "READY" "ACTIVE" "READY_NOT_ACTIVE" "PAUSED" "ENABLED"

Maps to Google Ads remote status:

  • ACTIVE / ENABLED → ENABLED
  • READY / READY_NOT_ACTIVE / PAUSED → PAUSED
include_related
boolean
Default: true

When true, propagates the status change to related ad groups and ads

Responses

Request samples

Content type
application/json
{
  • "task_status": "READY",
  • "include_related": true
}

Add or remove a keyword from a cluster

Adds or removes a single keyword (or comma-separated list) from a keyword cluster. For add operations, keyword metrics are fetched asynchronously. For remove, the keyword is immediately deleted.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
keyword
required
string

Single keyword or comma-separated list of keywords

action
required
string
Enum: "add" "remove"

Responses

Request samples

Content type
application/json
{
  • "keyword": "project management software",
  • "action": "add"
}

Bulk keyword add/remove operation (async)

Adds or removes keywords across multiple keyword clusters asynchronously. Returns a task ID for polling. Used for bulk editing keyword sets in the UI.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Regenerate keyword clusters for a product

Triggers AI-powered regeneration of keyword clusters for the specified product. Existing unapproved clusters are replaced. Returns a task ID for async polling.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Bulk create keyword clusters for products

Triggers keyword cluster generation for multiple products simultaneously.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
product_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Approve a keyword cluster

Marks a keyword cluster as approved, making its ad group eligible for publishing.

Authorizations:
apiKeyAuth

Responses

Disapprove a keyword cluster

Reverts a keyword cluster approval, preventing ad group publishing.

Authorizations:
apiKeyAuth

Responses

Delete a keyword cluster

Soft-deletes a keyword cluster and its associated ad group.

Authorizations:
apiKeyAuth

Responses

Bulk approve keyword clusters

Approves multiple keyword clusters in a single operation.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
cluster_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "cluster_ids": [
    ]
}

Bulk disapprove keyword clusters

Disapproves multiple keyword clusters at once. Pauses any that are already live on Google Ads and reverts local-only clusters to pending.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
cluster_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "cluster_ids": [
    ]
}

Bulk delete keyword clusters

Soft-deletes multiple keyword clusters. For clusters published to Google Ads, removes their ad groups and related ads remotely before deleting locally.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
cluster_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "cluster_ids": [
    ]
}

Bulk create ad content from keyword clusters

Triggers AI generation of responsive search ads for multiple keyword clusters. Returns a task ID for async polling.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
cluster_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "cluster_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Create an ad group manually with AI

Creates a new keyword cluster and ad group for the specified campaign using AI, either from scratch (create_manually) or seeded from provided keywords (create_from_keywords).

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
campaign_id
required
integer
ad_group_name
required
string <= 255 characters
creation_type
required
string
Enum: "create_manually" "create_from_keywords"
ai_instructions
required
string <= 1000 characters

Custom instructions for AI ad group generation

keywords
Array of strings

Required when creation_type is "create_from_keywords"

Responses

Request samples

Content type
application/json
{
  • "campaign_id": 55,
  • "ad_group_name": "Project Management Software",
  • "creation_type": "create_from_keywords",
  • "ai_instructions": "Focus on enterprise teams and productivity",
  • "keywords": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Otto PPC: Ad Content & Creative

Responsive search ads (headlines, descriptions), asset management, and approval workflows

List ad content (RSAs)

Returns responsive search ads filterable by business_id, campaign_id, product_id, ad_group_id, is_approved, and keyword_cluster_id. Includes performance metrics (clicks, impressions, CTR, conversions, cost).

Authorizations:
apiKeyAuth
query Parameters
business_id
integer
campaign_id
integer
product_id
integer
ad_group_id
integer
is_approved
boolean
keyword_cluster_id
integer
internal_campaign_type
string
Default: "SEARCH"
Enum: "SEARCH" "RETARGETED"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update ad content

Updates headlines, descriptions, landing page, and/or display path for a responsive search ad. Also handles sitelink, callout, and structured snippet assets. Duplicate headlines/descriptions are automatically deduplicated.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
headlines
Array of strings <= 15 items
descriptions
Array of strings <= 4 items
landing_page
string <uri>
display_path
Array of strings <= 2 items
object

Campaign asset updates grouped by type

Responses

Request samples

Content type
application/json
{
  • "headlines": [
    ],
  • "descriptions": [
    ],
  • "landing_page": "http://example.com",
  • "display_path": [
    ],
  • "assets_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "ad_group_id": 0,
  • "keyword_cluster_id": 0,
  • "ad_group_name": "string",
  • "landing_page": "http://example.com",
  • "display_path": [
    ],
  • "headlines": [
    ],
  • "primary_headline": "string",
  • "descriptions": [
    ],
  • "is_approved": true,
  • "assets": {
    },
  • "remote_id": "string",
  • "remote_status": "string",
  • "ad_sync_status": "string",
  • "ad_sync_error_msg": "string",
  • "google_ads_url": "http://example.com",
  • "clicks": 0,
  • "ctr": 0,
  • "cost": 0,
  • "conversions": 0,
  • "impressions": 0
}

Delete an ad

Soft-deletes an ad. If the ad has been published to Google, also removes it from Google Ads.

Authorizations:
apiKeyAuth

Responses

Update ad remote status

Enables or pauses a specific ad on Google Ads.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
task_status
required
string
Enum: "READY" "ACTIVE" "READY_NOT_ACTIVE" "PAUSED" "ENABLED"

Maps to Google Ads remote status:

  • ACTIVE / ENABLED → ENABLED
  • READY / READY_NOT_ACTIVE / PAUSED → PAUSED
include_related
boolean
Default: true

When true, propagates the status change to related ad groups and ads

Responses

Request samples

Content type
application/json
{
  • "task_status": "READY",
  • "include_related": true
}

Approve an ad

Marks an ad as approved, making it eligible for publishing to Google Ads.

Authorizations:
apiKeyAuth

Responses

Disapprove an ad

Reverts an ad approval.

Authorizations:
apiKeyAuth

Responses

Bulk approve ads

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
ad_content_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "ad_content_ids": [
    ]
}

Bulk disapprove ads

Disapproves multiple ads at once. Pauses ads already live on Google Ads and reverts local-only ads to unapproved.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
ad_content_ids
required
Array of integers

Responses

Request samples

Content type
application/json
{
  • "ad_content_ids": [
    ]
}

Bulk delete ads

Deletes multiple ads. For ads published to Google Ads, removes them remotely before deleting locally. Returns 400 if remote deletion fails.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
ad_content_ids
required
Array of integers
delete_from_google
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "ad_content_ids": [
    ],
  • "delete_from_google": false
}

Get ad content performance data

Returns performance metrics (impressions, clicks, CTR, cost, conversions) for ad content, with optional date range and campaign filtering.

Authorizations:
apiKeyAuth
query Parameters
business_id
required
integer
campaign_ids
string

Comma-separated campaign IDs

start_date
string <date>
end_date
string <date>

Responses

Response samples

Content type
application/json
{
  • "selected_dates": {
    },
  • "total_count": 0,
  • "total": {
    },
  • "results": [
    ],
  • "available_fields": [
    ]
}

Otto PPC: Ad Groups

Ad group listing and grouped ad content views

List ad groups

Returns ad groups with their associated campaign data. Filterable by business_id, campaign_id, and product_id.

Authorizations:
apiKeyAuth
query Parameters
business_id
integer
campaign_id
integer
product_id
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get ad groups with grouped ad contents

Returns ad groups with their ad content nested inside each group. Used for the grouped ad content view in the campaign management UI.

Authorizations:
apiKeyAuth
query Parameters
business_id
required
integer
campaign_id
integer
product_id
integer
is_approved
boolean

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Otto PPC: Sync

Bidirectional sync between OTTO PPC and Google Ads accounts

Sync campaigns from Google Ads

Triggers a full bidirectional sync between OTTO PPC and the specified Google Ads account. Pulls campaign status, ad performance metrics, keywords, and negative keywords from Google. Returns a task ID for async polling.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending"
}

Get sync status for an ads account

Returns the current sync status and last sync timestamp for the specified Google Ads account.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "sync_status": "PENDING",
  • "last_synced_at": "2019-08-24T14:15:22Z",
  • "task_id": "string"
}

Otto PPC: Tasks

Async task status polling for long-running operations

Get async task results

Polls the status and result of a background Celery task. All async operations (keyword generation, campaign creation, product discovery, etc.) return a task_id that can be polled here.

Task statuses: pending → in_progress → success | error | timeout

Authorizations:
apiKeyAuth
path Parameters
taskId
required
string

Celery task ID returned by async endpoints

Responses

Response samples

Content type
application/json
{
  • "task_id": "string",
  • "status": "pending",
  • "result": { },
  • "error": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

Otto PPC: Campaign Performance

Campaign-level Google Ads performance metrics, charts, KPIs, and exports

List campaign performance data

Returns paginated campaign performance rows from Google Ads for the given date range. Requires either business_id, campaign_ids, or ads_account_id. Metrics are fetched live from Google Ads API and merged with local campaign data.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "page": 0,
  • "page_size": 0,
  • "results": [
    ],
  • "totals": {
    }
}

Otto PPC: Ad Group Performance

Ad group-level performance metrics, scatter plots, and exports

List ad group performance data

Returns paginated ad group performance rows from Google Ads for the given date range. Supports filtering by campaign name, campaign IDs, and status filters.

Authorizations:
apiKeyAuth
query Parameters
campaign_name
string

Filter by campaign name substring

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "page": 0,
  • "page_size": 0,
  • "results": [
    ],
  • "totals": {
    }
}

Otto PPC: Audit - Campaign Efficiency

Audit pillar - campaign efficiency scoring and per-campaign analysis

Trigger a new audit run

Triggers an asynchronous audit across all 5 pillars for the given Google Ads account. If an audit with the same parameters was run today, returns the existing audit unless allow_duplicate is true. Returns 202 while pending, 200 if already complete.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
ads_account_id
required
integer

ID of the Google Ads account to audit

start_date
required
string <date>
end_date
required
string <date>
campaign_type_filter
string or null

Optionally restrict audit to a specific advertising channel type

campaign_ids
Array of integers or null

Optionally restrict audit to specific campaigns

campaign_status
string
Default: "ACTIVE"
Enum: "ACTIVE" "PAUSED" "ALL"
allow_duplicate
boolean
Default: true

If true, always create a new audit even if one exists for today

Responses

Request samples

Content type
application/json
{
  • "ads_account_id": 42,
  • "start_date": "2025-01-01",
  • "end_date": "2025-01-31",
  • "campaign_status": "ACTIVE",
  • "allow_duplicate": true
}

Response samples

Content type
application/json