digitalpublic-com Project Groups API

openapi: 3.2.0
info:
  title: DigitalPublic Agent Project Groups 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: ProjectGroups
paths:
  /api/project-groups/agent-query:
    post:
      summary: Project-group context and aggregated metrics
      description: 'Read groups available to a dpa_ agent. Group calls do not replace project scoping: all ordinary service endpoints still require a concrete projectId.'
      tags:
      - ProjectGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
      x-tools:
      - name: list_groups
        description: List accessible project groups and effective scopes.
        params: {}
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_group
        description: Read shared group context, reporting currency and timezone.
        params:
          groupId:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_group_projects
        description: List current projects in a group. Group access automatically covers projects added later.
        params:
          groupId:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_group_metrics
        description: Aggregate normalized source snapshots with project names, CRM leads, GA4/Search Console configuration states, daily GA4 traffic, key-event, channel and source/medium breakdowns, and weighted rates. Unique visitors and GA4 users are explicitly per-property sums.
        params:
          groupId:
            type: string
            required: true
          from:
            type: string
            required: true
          to:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_group_funnel
        description: Read group lead, qualified-conversation, proposal and won-pilot funnel.
        params:
          groupId:
            type: string
            required: true
          from:
            type: string
            required: true
          to:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_group_mailing_config
        description: Read safe group newsletter configuration and per-project permissions. Secrets are never returned.
        params:
          groupId:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_group_shared_newsletters
        description: List project-owned newsletters shared by reference with the group.
        params:
          groupId:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_mailing_conversion_preview
        description: Preview a complete project-to-group mailing conversion and its blockers.
        params:
          groupId:
            type: string
            required: true
          projectId:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      operationId: postApiProjectGroupsAgentQuery
      x-operation-id-source: derived
  /api/project-groups/agent-mutate:
    post:
      summary: Refresh project-group metrics
      description: Idempotently refresh normalized snapshots with bounded concurrency. Source failures are persisted independently instead of failing the whole refresh.
      tags:
      - ProjectGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Refresh result
      x-tools:
      - name: refresh_group_metrics
        description: Refresh Landing/Sites, CRM, GA4, Search Console, Google Ads and AEO snapshots for every current group project. Requires group write scope.
        params:
          groupId:
            type: string
            required: true
          from:
            type: string
            optional: true
            description: ISO date; default 30 days before to.
          to:
            type: string
            optional: true
            description: ISO date; default now.
          concurrency:
            type: number
            optional: true
            description: 1-5, default 2.
        x-mcp:
          channel: project_groups
          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: set_group_mailing_project_permission
        description: Set NONE, READ or EDIT plus independent agent/form access for a project that currently belongs to the group.
        params:
          groupId:
            type: string
            required: true
          projectId:
            type: string
            required: true
          accessLevel:
            type: string
            required: true
            enum:
            - NONE
            - READ
            - EDIT
          agentsEnabled:
            type: boolean
            required: true
          formsEnabled:
            type: boolean
            required: true
        x-mcp:
          channel: project_groups
          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: move_subscriptions_to_group
        description: Copy active subscriptions with verified evidence from a project newsletter into a group newsletter after human approval.
        params:
          groupId:
            type: string
            required: true
          projectId:
            type: string
            required: true
          sourceNewsletterId:
            type: string
            required: true
          targetNewsletterId:
            type: string
            required: true
          idempotency_key:
            type: string
            required: true
          agent_note:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: write
          requiredScope: write
          approval: human
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: share_newsletter_with_group
        description: Share a project-owned newsletter with every project in its group without moving data.
        params:
          groupId:
            type: string
            required: true
          projectId:
            type: string
            required: true
          newsletterId:
            type: string
            required: true
          legalConfirmation:
            type: string
            required: true
          idempotency_key:
            type: string
            required: true
          agent_note:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: write
          requiredScope: write
          approval: human
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: unshare_newsletter_from_group
        description: Remove group access to a shared newsletter without deleting its project-owned data.
        params:
          groupId:
            type: string
            required: true
          projectId:
            type: string
            required: true
          newsletterId:
            type: string
            required: true
          idempotency_key:
            type: string
            required: true
          agent_note:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: write
          requiredScope: write
          approval: human
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: convert_project_mailings_to_group
        description: Convert the complete project mailing configuration into the group scope while preserving identifiers and history.
        params:
          groupId:
            type: string
            required: true
          projectId:
            type: string
            required: true
          legalConfirmation:
            type: string
            required: true
          idempotency_key:
            type: string
            required: true
          agent_note:
            type: string
            required: true
        x-mcp:
          channel: project_groups
          effect: write
          requiredScope: write
          approval: human
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      operationId: postApiProjectGroupsAgentMutate
      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