digitalpublic-com SEO API

openapi: 3.2.0
info:
  title: DigitalPublic Agent SEO 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: SEO
paths:
  /api/seo-tools/agent-query:
    post:
      summary: SEO tools
      description: Query SEO metrics for the project's configured domain. DigitalPublic resolves the underlying SEO data source; agents never address it directly.
      tags:
      - SEO
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
      x-tools:
      - name: seo_domain_overview
        description: Domain overview with regional and worldwide metrics.
        params:
          domain:
            type: string
            optional: true
          db:
            type: string
            default: es
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_domain_keywords
        description: Organic tracked keywords for the project domain. Configured target keywords are always preserved and missing targets are reported explicitly.
        params:
          domain:
            type: string
            optional: true
          db:
            type: string
            default: es
          limit:
            type: number
            default: 50
            maximum: 500
          keywords:
            type: string|array
            optional: true
          query:
            type: string
            optional: true
        returns:
          keywords: Array<{ keyword, position, prev_pos, url, volume, intents }>
          targetKeywords: string[]
          missingTargetKeywords: string[]
          resultCount: number
          limit: number
        x-mcp:
          channel: seo_tools
          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: seo_backlinks_summary
        description: Backlink profile summary.
        params:
          domain:
            type: string
            optional: true
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_backlinks_changes
        description: Backlink history/changes.
        params:
          domain:
            type: string
            optional: true
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_backlinks_anchors
        description: Anchor text distribution.
        params:
          domain:
            type: string
            optional: true
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_competitors
        description: SEO competitors analysis.
        params:
          domain:
            type: string
            optional: true
          source:
            type: string
            default: es
          type:
            type: string
            default: organic
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_keyword_research
        description: Research keywords with volumes, CPC, difficulty and intents.
        params:
          keywords:
            type: string|array
            required: true
            aliases:
            - keyword
            - query
            - term
          source:
            type: string
            default: es
          sort:
            type: string
            optional: true
          sort_order:
            type: string
            optional: true
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_keyword_questions
        description: Related questions for a keyword.
        params:
          keyword:
            type: string
            required: true
            aliases:
            - query
            - term
          source:
            type: string
            default: es
          limit:
            type: number
            default: 100
          offset:
            type: number
            default: 0
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_serp_results
        description: 'SERP results for a keyword via an asynchronous SERP task. Every call without task_id creates a billable task, so the cycle is: call once with keyword, read taskId in the response, and if status is ''processing'' call again with ONLY task_id (never resend the keyword). Two identical keyword calls within 15 minutes reuse the same task.'
        params:
          keyword:
            type: string
            required: unless task_id is sent
            aliases:
            - query
            - term
          task_id:
            type: string|number
            optional: true
            aliases:
            - taskId
            - serp_task_id
            description: Id returned by a previous call. When present the task is only read, never re-created, and keyword/location params are ignored.
          language_code:
            type: string
            default: es
          google_ads_location_id:
            type: number
            default: 2724
            description: Google Ads geo target id (2724 = Spain, 2276 = Germany, 2840 = United States), from the public Google Ads geo target constants table. Recommended way to target a country.
          location_id:
            type: number
            optional: true
            aliases:
            - region_id
            description: 'Id from the SEO data provider''s OWN location catalog, a different catalog from Google Ads: the same number means a different place (or none at all) in each one. Never translate an id between catalogs. If you only know the Google Ads geo target id, send google_ads_location_id instead. When both are sent, location_id wins.'
          device:
            type: string
            default: desktop
          limit:
            type: number
            default: 10
          waitMs:
            type: number
            default: 15000
            description: How long the call waits for the task before returning status 'processing' with its taskId (max 25000).
        returns:
          taskId: string
          status: completed | processing | submitted
          reusedExistingTask: boolean
          result: SERP payload when completed
          retrieveWith: exact follow-up call when the task is still processing
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_domain_pages
        description: Top pages by organic traffic.
        params:
          domain:
            type: string
            optional: true
          source:
            type: string
            default: es
          scope:
            type: string
            default: base_domain
          type:
            type: string
            default: organic
          limit:
            type: number
            default: 20
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: seo_ai_overview
        description: AI search visibility metrics.
        params:
          domain:
            type: string
            optional: true
          source:
            type: string
            default: es
          engine:
            type: string
            default: ai-overview
          scope:
            type: string
            default: base_domain
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: download_seo_report_pdf
        description: Get report data and PDF download URL.
        params:
          reportId:
            type: string
            required: true
        x-mcp:
          channel: seo_tools
          effect: report_generation
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: BACKGROUND
            resourceClass: HEAVY
            priority: BULK
            costModel: ESTIMATED
            idempotencyMode: REQUIRED
      - name: list_seo_reports
        description: List SEO reports with stable source, detailTool, fileTool and contentUnavailable metadata for historical files.
        params:
          limit:
            type: number
            default: 10
        x-mcp:
          channel: seo_tools
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: submit_seo_analysis
        description: Submit the analysis/briefing for a SEO report (requires write scope).
        params:
          reportId:
            type: string
            required: true
          analysis:
            type: object
            description: '{ resumenEjecutivo, logros, alertas, propuestasMejora, proximosPasos }'
        x-mcp:
          channel: seo_tools
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      operationId: postApiSeoToolsAgentQuery
      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