API docs by Redocly

ultra-api Marketing Agent API (0.24.0)

Download OpenAPI specification:

License: MIT

Contract-first OpenAPI spec for an AI-agent optimized marketing surface.

This API is intentionally not a raw mirror of the existing marketing routes. It exposes a small tool layer that an agent can call with explicit workspace scope, predictable inputs, audit context, and bounded outputs.

How to use this reference

The Marketing Agent API has only two HTTP operations:

  1. Discover available tools with GET /marketing/agent/capabilities.
  2. Execute exactly one tool with POST /marketing/agent/tools/{toolName}.

The tool catalog returned by the capabilities endpoint is the runtime source of truth for tool descriptions and JSON schemas. This OpenAPI reference is organized around the operational families below so an agent builder can find the right tool without scanning one long mixed list.

Authentication

All endpoints require a super-admin Bearer token for the first iteration. The runtime must reject non super-admin tokens even when the user belongs to the target workspace.

Workspace Scope

Mutating and workspace-scoped tool calls require organizationId. Agents that only have a human name, slug, owner email, or ambiguous operator input must first call marketing_resolve_workspace, then use the returned technical organizationId for subsequent scoped tools.

Response Envelope

All responses use the ApiResponse envelope:

{ "success": true|false, "data": ..., "error": "...", "meta": {...} }

Tool Contract

GET /marketing/agent/capabilities lists available tools and their JSON schemas. POST /marketing/agent/tools/{toolName} executes one tool with a single scoped input payload.

Tool Families

Family Tools
Workspace administration marketing_resolve_workspace, get_workspace_marketing_summary, create_marketing_workspace, update_marketing_workspace, add_workspace_member, remove_workspace_member
Social accounts list_social_accounts, assign_social_account, unassign_social_account, refresh_social_account, disconnect_social_account
Publications and planner list_publications, get_publication_detail, get_publication_logs, preview_publication, refresh_publication_status, get_planner, create_content_item, update_publication, schedule_publication, publish_publication, cancel_scheduled_publication, duplicate_publication, bulk_move_publications, bulk_duplicate_publications, bulk_delete_publications
Provider post operations edit_published_facebook_post, delete_published_facebook_post, import_external_page_posts, reconcile_external_page_posts, list_external_page_posts, get_external_page_post_detail, import_external_instagram_media, list_external_instagram_media, get_external_instagram_media_detail
Content workflow and library list_content_items, get_content_item, bulk_delete_content_items, review tools, notes, checklists, templates, caption sets, hashtag sets, UTM presets, queues, and recurrence tools
Inbox marketing_bulk_import_messages, sync_inbox_threads, thread/contact/event/task listing, priority, assignment, resolve/reopen/snooze, labels, notes (thread and contact), replies, and bulk resolution
Analytics and reports overview, posts, accounts, campaigns, trends, benchmarks, top content, performance, metric refresh, report templates, report runs, and transient report generation
Growth and ads growth campaigns, campaign attribution, smart links, short links, touchpoints, conversions, funnel, ad account discovery/linking/sync, ad campaigns, ad insights, and insights ingestion
Media and maintenance media upload/list/delete tools, backfill jobs (start/list/retry/cancel), and purge_external_imported_posts

1. Capability Discovery

Tool discovery and schema metadata

List available Marketing Agent tools

Returns the tool catalog, input schemas, output schemas, auth policy, and defaults.

Authorizations:
bearerAuth
query Parameters
organizationId
string

Optional workspace filter for capability checks.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "error": "string",
  • "meta": {
    }
}

2. Tool Execution

Scoped marketing tool execution

Execute one Marketing Agent tool

Executes a scoped marketing operation with explicit workspace id and audit context.

Authorizations:
bearerAuth
path Parameters
toolName
required
string (MarketingAgentToolName)
Enum: "get_workspace_marketing_summary" "marketing_resolve_workspace" "create_marketing_workspace" "update_marketing_workspace" "add_workspace_member" "remove_workspace_member" "list_social_accounts" "assign_social_account" "unassign_social_account" "refresh_social_account" "disconnect_social_account" "list_publications" "get_publication_detail" "get_publication_logs" "preview_publication" "refresh_publication_status" "list_content_items" "get_content_item" "get_analytics_overview" "list_top_content" "get_campaign_performance" "list_analytics_posts" "list_analytics_accounts" "list_analytics_campaigns" "get_analytics_trends" "get_analytics_benchmarks" "get_best_times" "recompute_best_times" "refresh_analytics_metrics" "list_analytics_ingestion_jobs" "get_planner" "marketing_bulk_import_messages" "sync_inbox_threads" "list_inbox_threads" "get_inbox_thread" "get_inbox_dashboard" "get_all_inbox_dashboards" "list_inbox_contacts" "get_inbox_contact" "add_inbox_contact_note" "list_inbox_thread_events" "list_my_inbox_tasks" "update_inbox_thread_priority" "assign_inbox_thread" "resolve_inbox_thread" "bulk_resolve_inbox_threads" "bulk_resolve_inbox_threads_by_filter" "bulk_classify_inbox_threads" "bulk_label_inbox_threads" "bulk_snooze_inbox_threads" "bulk_assign_inbox_threads" "detect_inbox_security_risks" "get_unresolved_inbox_digest" "sync_inbox_threads_rate_limited" "bulk_resolve_with_audit_note" "reopen_inbox_thread" "snooze_inbox_thread" "add_inbox_thread_label" "remove_inbox_thread_label" "add_inbox_thread_note" "reply_to_inbox_thread" "get_growth_overview" "list_growth_campaigns" "get_growth_campaign" "get_growth_campaign_attribution" "create_growth_campaign" "update_growth_campaign" "delete_growth_campaign" "list_smart_links" "get_smart_link" "create_smart_link" "update_smart_link" "publish_smart_link" "duplicate_smart_link" "list_short_links" "get_short_link" "create_short_link" "update_short_link" "list_growth_touchpoints" "list_growth_conversions" "get_growth_funnel" "list_report_templates" "list_report_runs" "create_report_template" "update_report_template" "delete_report_template" "schedule_report_template" "list_ads_campaigns" "list_ad_accounts" "discover_ad_accounts" "link_ad_accounts" "unlink_ad_account" "sync_ad_account_campaigns" "get_ad_campaign_detail" "get_ad_insights_overview" "list_ad_insights_campaigns" "get_ad_insights_campaign_history" "get_ad_insights_trends" "ingest_ad_insights" "list_media_assets" "delete_media_asset" "bulk_delete_media_assets" "start_backfill_job" "list_backfill_jobs" "retry_backfill_jobs" "cancel_backfill_job" "run_report" "create_content_item" "update_publication" "edit_published_facebook_post" "delete_published_facebook_post" "schedule_publication" "publish_publication" "cancel_scheduled_publication" "duplicate_publication" "bulk_move_publications" "bulk_duplicate_publications" "bulk_delete_publications" "bulk_delete_content_items" "submit_content_review" "approve_content" "reject_content" "assign_content" "list_content_notes" "add_content_note" "update_content_note" "delete_content_note" "list_content_checklists" "create_content_checklist" "add_content_checklist_item" "update_content_checklist_item" "delete_content_checklist" "list_content_templates" "create_content_template" "update_content_template" "delete_content_template" "list_caption_sets" "create_caption_set" "update_caption_set" "delete_caption_set" "list_hashtag_sets" "create_hashtag_set" "update_hashtag_set" "delete_hashtag_set" "list_utm_presets" "create_utm_preset" "update_utm_preset" "delete_utm_preset" "list_queue_categories" "create_queue_category" "update_queue_category" "delete_queue_category" "enqueue_content_to_queue" "list_recurrence_rules" "create_recurrence_rule" "update_recurrence_rule" "delete_recurrence_rule" "prepare_media_upload" "complete_media_upload" "list_external_page_posts" "get_external_page_post_detail" "import_external_page_posts" "reconcile_external_page_posts" "list_external_instagram_media" "get_external_instagram_media_detail" "import_external_instagram_media" "purge_external_imported_posts"
Request Body schema: application/json
required
organizationId
required
string

Explicit target marketing workspace.

required
object or object or object or ListSocialAccountsInput (object) or object or object or object or object or ListPublicationsInput (object) or object or PublicationLogsInput (object) or ListContentItemsInput (object) or object or object or TopContentInput (object) or CampaignPerformanceInput (object) or AnalyticsPostsInput (object) or AnalyticsAccountsInput (object) or AnalyticsCampaignsInput (object) or object or object or object or object or object or InboxThreadsInput (object) or object or object or InboxContactsInput (object) or object or InboxThreadEventsInput (object) or InboxTasksInput (object) or object or object or object or (object or object or object) or object or (object or object) or object or object or object or object or GrowthCampaignsInput (object) or object or SmartLinksInput (object) or object or ShortLinksInput (object) or object or GrowthTouchpointsInput (object) or GrowthConversionsInput (object) or object or ReportTemplatesInput (object) or ReportRunsInput (object) or AdsCampaignsInput (object) or AdAccountsInput (object) or object or object or AdInsightsCampaignsInput (object) or object or object or MediaAssetsInput (object) or object or object or object or BackfillJobsInput (object) or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or ListLibraryItemsInput (object) or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or ListRecurrenceRulesInput (object) or object or object or object or object or object or ListExternalPagePostsInput (object) or (object or object or object or object) or object or ReconcileExternalPagePostsInput (object) or ListExternalInstagramMediaInput (object) or (object or object or object or object) or object or object (MarketingAgentToolInput)
dryRun
boolean
Default: false

Validate and plan execution without applying mutations when supported.

reason
string <= 500 characters

Human-readable reason stored in audit logs.

requestId
string <= 120 characters

Optional caller idempotency or trace identifier.

Responses

Request samples

Content type
application/json
Example
{
  • "organizationId": "org_123",
  • "input": {
    },
  • "reason": "Create a workspace requested by the account owner."
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "error": "string",
  • "meta": {
    }
}