digitalpublic-com AEO API

openapi: 3.2.0
info:
  title: DigitalPublic Agent AEO API
  version: 2026-09-10-trial-active-projects-v1
  description: API for external AI agents to interact with DigitalPublic projects. Provides discovery, project context, Google Ads, Meta Ads, LinkedIn organic and LinkedIn Ads, Merchant Center, SEO, AEO, Search Console, WordPress, Analytics, Tag Manager, Business Profile, mailings, CRM, comments, reports, and scheduling.
  contact:
    email: soporte@digitalpublic.com
servers:
- url: https://platform.digitalpublic.com
  description: Production
security:
- bearerAuth: []
tags:
- name: AEO
paths:
  /api/aeo/agent-query:
    post:
      summary: AEO / AI search visibility
      description: Query AI search visibility for the project's configured brand, prompts, and engines.
      tags:
      - AEO
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
      x-tools:
      - name: get_se_visible_availability
        description: Read SE Visible availability for this project, with explicit unknown results and safe reasonCode. Only agents with global read scope receive authorized quotas and inventory. This read does not activate a connection.
        params: {}
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_aeo_capacity
        description: Read AEO prompt availability. Aggregate counts require global read scope.
        params: {}
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_aeo_configuration
        description: Freeze brand, complete prompts and engines from the bound provider with a deterministic snapshot hash. SE Visible bindings use live SE Visible configuration and retain legacy fields separately.
        params: {}
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: aeo_overview
        description: Brand visibility overview by configured AI engine. Every engine distinguishes VALID, UNAVAILABLE, ERROR and PENDING.
        params:
          from:
            type: string
            optional: true
          to:
            type: string
            optional: true
          top:
            type: number
            optional: true
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: aeo_prompt_rankings
        description: Prompt ranking rows for ChatGPT, Gemini, Perplexity, Google AI Overview, or Google AI Mode, with an explicit resultState.
        params:
          engine:
            type: string
            optional: true
          date_from:
            type: string
            optional: true
          date_to:
            type: string
            optional: true
          limit:
            type: number
            default: 100
          offset:
            type: number
            default: 0
          mode:
            type: string
            optional: true
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: aeo_prompt_answer
        description: Cached AI answer for a specific prompt ranking ID, with an explicit resultState.
        params:
          engine:
            type: string
            optional: true
          prompt_llm_id:
            type: string
            required: true
          date:
            type: string
            optional: true
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: aeo_visible_project
        description: Read the SE Visible project bound to this DigitalPublic project.
        params: {}
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: aeo_visible_prompts
        description: List SE Visible prompts and provider metrics with metricReconciliation. Use reportingMetrics for reports; zero mentions require reconciliation with underlying responses and brand aliases.
        params:
          from:
            type: string
            optional: true
          to:
            type: string
            optional: true
          model:
            type: string
            optional: true
          limit:
            type: number
            default: 100
          offset:
            type: number
            default: 0
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: aeo_visible_results
        description: List SE Visible model runs with qualitative mentionReconciliation. Preserve provider flags; conflicting brand or domain evidence excludes zero-mention conclusions.
        params:
          promptId:
            type: number
            required: true
          from:
            type: string
            optional: true
          to:
            type: string
            optional: true
          model:
            type: string
            optional: true
          limit:
            type: number
            default: 100
          offset:
            type: number
            default: 0
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: aeo_visible_result
        description: Read one SE Visible result with full response, sources and qualitative mentionReconciliation. Conflicting evidence requires reconciliation before reporting zero mentions; it does not establish causal improvement or global visibility.
        params:
          promptId:
            type: number
            required: true
          resultId:
            type: number
            required: true
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          processEligible: true
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_aeo_reports
        description: List generated AEO reports.
        params:
          limit:
            type: number
            default: 10
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: check_mutation_status
        description: Check one AEO mutation.
        params:
          mutationId:
            type: string
            required: true
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_pending_mutations
        description: List pending AEO mutations.
        params:
          limit:
            type: number
            default: 20
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_mutation_history
        description: List AEO mutation history.
        params:
          status:
            type: string
            default: all
          limit:
            type: number
            default: 20
        x-mcp:
          channel: aeo
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      operationId: postApiAeoAgentQuery
      x-operation-id-source: derived
  /api/aeo/agent-mutate:
    post:
      summary: Configure AEO and prompts
      description: Queue AEO configuration and prompt changes. The AEO site must already exist in DigitalPublic. Requires write scope and human approval unless AEO auto-approval is enabled.
      tags:
      - AEO
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Validated, queued, or executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
      x-resources:
      - resource: aeo_config
        operations:
        - update
        description: Update brandName, countryCode, langCode, regionName, enabledEngines, optional seVisibleProjectId, and the existing AEO site identifier (field name `seRankingSiteId`, kept for API compatibility).
        x-mcp:
          channel: aeo
          effect: write
          requiredScope: write
          approval: auto_approval_possible
          requestShape: resource_operation
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - resource: aeo_prompts
        operations:
        - add
        - remove
        description: Add or remove promptKeywords in the canonical bound provider and verify its live catalogue. SE Visible inherits project language/location, requires current connection write consent, and preserves local legacy configuration. Optional context must be verifiable; topicId must belong to the bound SE Visible project.
        params:
          data:
            type: array
            required: true
            minItems: 1
            maxItems: 1
            items:
              type: object
              required:
              - promptKeywords
              additionalProperties: false
              properties:
                countryCode:
                  type: string
                  pattern: ^[a-zA-Z]{2}$
                langCode:
                  type: string
                  pattern: ^[a-zA-Z]{2}$
                regionName:
                  type:
                  - string
                  - 'null'
                topicId:
                  type: integer
                  minimum: 1
                promptKeywords:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    type: string
                    minLength: 1
        x-mcp:
          channel: aeo
          effect: write
          requiredScope: write
          approval: auto_approval_possible
          requestShape: resource_operation
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      operationId: postApiAeoAgentMutate
      x-operation-id-source: derived
components:
  schemas:
    AgentRequest:
      type: object
      required:
      - tool
      properties:
        tool:
          type: string
          description: Tool name to execute
        params:
          type: object
          description: Tool-specific parameters
          default: {}
        projectId:
          type: string
          description: Required when using a dpa_ global agent token. dpk_ project API keys infer the project automatically.
    AgentResponse:
      type: object
      properties:
        ok:
          type: boolean
        status:
          type: string
          description: executed, queued, pending_approval, or a domain-specific status
        operationId:
          type: string
          description: Persistent operation id when work continues in the background.
        resourceClass:
          type: string
          enum:
          - LIGHT
          - STANDARD
          - HEAVY
        retryAfterSeconds:
          type: integer
        data:
          type: object
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Project API key starting with dpk_ or global agent token starting with dpa_. dpa_ requests must include projectId or X-DigitalPublic-Project-Id for project-scoped endpoints.
x-commercial-channels:
- key: google_ads
  label:
    es: Google Ads
    en: Google Ads
  commercialModule: google_ads
  services:
  - googleAds
  mcpChannels:
  - google_ads
  public: true
  availability: generally_available
  access: read_write
  requiresConnection: true
  acceptedAliases:
  - google-ads
- key: wordpress
  label:
    es: WordPress
    en: WordPress
  commercialModule: seo_aeo
  services:
  - wordpressSeo
  mcpChannels:
  - wordpress
  public: true
  availability: generally_available
  access: read_write
  requiresConnection: true
  acceptedAliases:
  - wordpress-seo
- key: crm
  label:
    es: CRM
    en: CRM
  commercialModule: crm
  services:
  - crm
  mcpChannels:
  - crm
  public: true
  availability: generally_available
  access: read_write
  requiresConnection: true
  acceptedAliases: []
- key: websites
  label:
    es: Sitios web
    en: Websites
  commercialModule: content_web
  services:
  - landingPages
  mcpChannels:
  - landing_pages
  public: true
  availability: generally_available
  access: read_write
  requiresConnection: true
  acceptedAliases:
  - landing-pages
  - landing_pages
  - sites-web
  - sites_web
- key: social
  label:
    es: Redes sociales
    en: Social media
  commercialModule: social
  services:
  - socialOrganic
  - socialX
  - socialLinkedIn
  mcpChannels:
  - social
  public: true
  availability: generally_available
  access: read_write
  requiresConnection: true
  acceptedAliases: []
- key: blog
  label:
    es: Blog
    en: Blog
  commercialModule: content_web
  services:
  - blog
  mcpChannels:
  - blog
  public: true
  availability: generally_available
  access: read_write
  requiresConnection: true
  acceptedAliases: []
- key: meta_ads
  label:
    es: Meta Ads
    en: Meta Ads
  commercialModule: meta_ads
  services:
  - metaAds
  mcpChannels:
  - meta_ads
  public: true
  availability: limited
  access: read_write
  requiresConnection: true
  acceptedAliases:
  - meta-ads
  - meta
- key: linkedin_ads
  label:
    es: LinkedIn Ads
    en: LinkedIn Ads
  commercialModule: linkedin_ads
  services:
  - linkedinAds
  mcpChannels:
  - linkedin_ads
  public: true
  availability: limited
  access: read_write
  requiresConnection: true
  acceptedAliases:
  - linkedin-ads
  - linkedin
- key: seo
  label:
    es: SEO y AEO
    en: SEO and AEO
  commercialModule: seo_aeo
  services:
  - seo
  - aeo
  mcpChannels:
  - seo_tools
  - aeo
  public: true
  availability: limited
  access: read_write
  requiresConnection: false
  acceptedAliases: []
- key: analytics
  label:
    es: Analítica
    en: Analytics
  commercialModule: analytics
  services:
  - analytics
  mcpChannels:
  - analytics
  public: true
  availability: limited
  access: read
  requiresConnection: true
  acceptedAliases: []
- key: search_console
  label:
    es: Search Console
    en: Search Console
  commercialModule: search_console
  services:
  - searchConsole
  mcpChannels:
  - search_console
  public: true
  availability: limited
  access: read_write
  requiresConnection: true
  acceptedAliases:
  - search-console
- key: email
  label:
    es: Email y newsletters
    en: Email and newsletters
  commercialModule: email_marketing
  services:
  - mailings
  mcpChannels:
  - mailings
  public: true
  availability: limited
  access: read_write
  requiresConnection: true
  acceptedAliases:
  - brevo