Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getcitable.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What it does

Emits a paid ad on an AI surface — ChatGPT Ads today, with adapters for Perplexity, Gemini, Grok, and Copilot landing as each engine opens advertising. Engine-agnostic by design: pick the engine, pass the engine-shaped payload, and Citable routes to the right adapter. Under the hood:
  1. The persona-intent matrix validates the creative content.
  2. Citable calls the engine adapter to create the campaign, ad group, or ad on the external system.
  3. The action is recorded so its 30-day citation impact can be measured.
Intent is always 'commercial' for emit_paid — paid placements exist to drive conversions, not just engagement. The caller cannot override this.

​
When to use

  • The user (or upstream agent) has decided to launch a paid placement against a specific prompt cluster.
  • recommend_paid_ad_strategy returned a proposal the user approved.

​
When not to use

​
Inputs

  • object_type ('campaign' | 'ad_group' | 'ad', required).
  • engine ('chatgpt' | 'perplexity' | 'gemini' | 'grok' | 'copilot', default 'chatgpt').
  • payload (object, required) — engine-shaped payload for the create API call (e.g. ChatGPT Ads campaign body).
  • persona_id (number, required) — persona this placement targets; drives matrix validation.
  • content (string, optional) — creative body to validate. Strongly recommended for 'ad' object_type.
  • parent_external_id (string, optional) — required for 'ad_group' / 'ad'; the parent campaign or ad_group external id.
  • citable_prompt_ids (number[], optional) — tracked prompts this placement is meant to win.
  • citable_hub_id (number, optional) — content id of the hub this ad amplifies (links spoke → hub for measurement).

​
Response

{
  "externalId": "campaign_abc123",
  "engine": "chatgpt",
  "objectType": "campaign",
  "payload": { "...": "engine-shaped echo" },
  "validation": {
    "status": "allowed",
    "violations": []
  }
}
On block: isError: true with structuredContent: { status: 'blocked' | 'no_connector' | 'error', ... }. For 'blocked', fix the creative or record an override out-of-band and retry. For 'no_connector', connect the engine under Connectors first.

​
Persona-intent validation

The matrix runs before the external adapter is called — no external system gets a side effect for content the matrix blocks. Intent is hard-coded to 'commercial'.

​
Example

Launch a ChatGPT Ads campaign targeting a buyer-stage prompt cluster, linked to a content hub: 
{
  "object_type": "campaign",
  "engine": "chatgpt",
  "persona_id": 412,
  "payload": {
    "name": "Q2 — vs Competitor X buyer prompts",
    "daily_budget_usd": 50,
    "targeting": { "prompts": ["best alternative to competitor x", "competitor x vs"] }
  },
  "content": "Citable helps brands get cited by ChatGPT, Perplexity, Gemini, and Copilot...",
  "citable_prompt_ids": [1902, 1908, 1911],
  "citable_hub_id": 17203
}