digitalpublic-com Connections API

openapi: 3.2.0
info:
  title: DigitalPublic Agent Connections 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: Connections
paths:
  /api/connections/agent-query:
    post:
      summary: Discover and inspect provider connections
      description: Lists connectable providers, requirements, statuses, assets, approval actions and health. Connection discovery is a core capability and remains available before a business module is connected, and also for projects that are not linked to a commercial account yet (those are served in read-only legacy mode, with connection ids prefixed by 'legacy:').
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Connection information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
      x-tools:
      - name: list_tools
        description: List Connection Center tools.
        params: {}
        x-mcp:
          channel: connections
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_available_connections
        description: List all supported providers, modes, requirements, readiness and project entitlement state.
        params: {}
        x-mcp:
          channel: connections
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_connection_requirements
        description: Explain human prerequisites, scopes and consent policy for one connector.
        params:
          connectorKey:
            type: string
            required: true
        x-mcp:
          channel: connections
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_connection_status
        description: 'List connection states for the selected project. Works for projects without a commercial account: their existing integrations are returned in read-only legacy mode.'
        params:
          provider:
            type: string
            optional: true
        x-mcp:
          channel: connections
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_connection_assets
        description: List provider assets discovered under a project connection, including Meta Facebook Pages available for explicit social selection.
        params:
          connectionId:
            type: string
            required: true
        x-mcp:
          channel: connections
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_connection_actions
        description: List supervised connection actions and their approval status.
        params:
          limit:
            type: number
            optional: true
        x-mcp:
          channel: connections
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: test_connection
        description: Perform a safe read-only provider check and return the effective connection status, recovery action, timestamp, and diagnostic reference. For Meta OAuth, refresh user Pages and, when granted, owned/shared business Pages. Return metaPageDiagnosis with the verified authorizing profile, grantedScopes, pageCount, userPages/businessPages coverage and unverified granularPageConsent. Distinguish a missing page-list permission from an empty result; a missing Page does not establish its cause. Preserve Ads and use the existing connection for reauthorization.
        params:
          connectionId:
            type: string
            required: true
          projectId:
            type: string
            required: false
        x-mcp:
          channel: connections
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      x-mcp:
        channel: connections
        effect: read
        requiredScope: read
        approval: none
        requestShape: tool_params
      operationId: postApiConnectionsAgentQuery
      x-operation-id-source: derived
  /api/connections/agent-mutate:
    post:
      summary: Start and supervise provider connections
      description: Agents may initiate onboarding and continue after human consent. OAuth consent is restricted to human account owners/admins. Disconnect requests are always supervised. Requires the project to be linked to a commercial account (409 COMMERCIAL_ACCOUNT_REQUIRED otherwise); reading connections does not.
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Connection workflow result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
      x-tools:
      - name: start_connection
        description: Create a session and return humanAuthorizationUrl. Pass connectionId to reauthorize the same connection while preserving bindings. Never request OAuth tokens in chat.
        params:
          connectorKey:
            type: string
            required: true
          mode:
            type: string
            enum:
            - OAUTH
            - MANAGED
            - BYO
            - PAIRING
            optional: true
          permission:
            type: string
            enum:
            - read
            - write
            optional: true
          connectionId:
            type: string
            optional: true
          desiredAssetId:
            type: string
            optional: true
          desiredAssetName:
            type: string
            optional: true
          desiredDomain:
            type: string
            optional: true
          returnUrl:
            type: string
            optional: true
        x-mcp:
          channel: connections
          effect: write
          requiredScope: read
          approval: human
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: select_connection_asset
        description: Bind a selected asset to the project after consent. Facebook Pages require explicit administrator selection in the project Connection Center (META_PAGE_ADMIN_SELECTION_REQUIRED).
        params:
          assetId:
            type: string
            required: true
          module:
            type: string
            required: true
          permission:
            type: string
            enum:
            - read
            - write
            optional: true
        x-mcp:
          channel: connections
          effect: write
          requiredScope: write
          approval: auto_approval_possible
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: request_disconnect
        description: Create a supervised disconnect request. Credentials remain active until approval and execution.
        params:
          connectionId:
            type: string
            required: true
          reason:
            type: string
            optional: true
          idempotencyKey:
            type: string
            required: true
        x-mcp:
          channel: connections
          effect: write
          requiredScope: read
          approval: human
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: execute_approved_connection_action
        description: Execute an action only after OWNER/ADMIN approval.
        params:
          actionId:
            type: string
            required: true
        x-mcp:
          channel: connections
          effect: write
          requiredScope: write
          approval: human
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      x-mcp:
        channel: connections
        effect: write
        requiredScope: read
        approval: human
        requestShape: tool_params
      operationId: postApiConnectionsAgentMutate
      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