digitalpublic-com Portfolio API

openapi: 3.2.0
info:
  title: DigitalPublic Agent Portfolio 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: Portfolio
paths:
  /api/portfolio/agent-query:
    post:
      summary: Portfolio-wide pending work
      description: Aggregated operational queue for every project within the effective global or group dpa_ credential. Uses bounded set queries, live freshness metadata and safe partial-failure codes. Project API keys and agents with only explicit project access are rejected.
      tags:
      - Portfolio
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: Portfolio summary or paginated detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
      x-tools:
      - name: portfolio_pending_summary
        description: Return task, CRM, site issue, mutation, editorial review, report and email pending counts for all accessible projects. Distinguishes ok, disabled, not_configured and safe error coverage states.
        params:
          asOf:
            type: string
            optional: true
            description: Authoritative ISO instant. Defaults to now.
          timezone:
            type: string
            optional: true
            description: IANA timezone used to calculate today. Defaults to Europe/Madrid.
          projectStatus:
            type: string
            enum:
            - active
            - inactive
            - all
            optional: true
            description: Defaults to active.
          groupId:
            type: string
            optional: true
            description: Restrict to an accessible group.
          include:
            type: array
            items:
              type: string
              enum:
              - tasks
              - crm
              - siteIssues
              - mutations
              - revisionRequests
              - emails
              - reports
            optional: true
          staleDays:
            type: number
            optional: true
            description: CRM stale threshold, 1-365. Defaults to 7.
          actionableIssuesOnly:
            type: boolean
            optional: true
            description: Use the actionable issue subset when deciding attention. Raw counts are always retained.
          unified:
            type: boolean
            optional: true
            description: Return the unified project cycle queue, ordered by actionable work and then age. Includes compact current process state, ready node, human waiting party and follow-up, blocker, verified action and authoritative decision references. Future follow-ups come after actionable work. Checks tasks/blockers, CRM, reports and emails. Unknown coverage prevents closure.
          reasons:
            type: array
            items:
              type: string
              enum:
              - tasks
              - crm
              - reports
              - emails
            optional: true
            description: OR filter for unified mode. Unknown coverage remains visible.
          cursor:
            type: string
            optional: true
            description: Unified cursor bound to snapshot and filters; reuse asOf. Changed data requires restarting pagination.
          limit:
            type: number
            optional: true
            description: Unified project page size, 1-100, default 50.
          countsOnly:
            type: boolean
            optional: true
            description: Return compact project identities, counts and coverage.
        x-mcp:
          channel: portfolio
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: portfolio_pending_items
        description: Return a cursor-paginated, PII-minimized detail page for one portfolio category. Task items include a compact cycle with current status, ready node, human wait, follow-up, blocker, last verified action, latest attributable human checkpoint and next step. Task cursors bind live state and effective access; reuse asOf and filters. The project set is always derived from the effective credential.
        params:
          category:
            type: string
            required: true
            enum:
            - tasks
            - crm
            - siteIssues
            - mutations
            - revisionRequests
            - emails
            - reports
          asOf:
            type: string
            optional: true
          timezone:
            type: string
            optional: true
          projectStatus:
            type: string
            enum:
            - active
            - inactive
            - all
            optional: true
          projectId:
            type: string
            optional: true
            description: May only narrow to an already accessible project.
          groupId:
            type: string
            optional: true
            description: May only narrow to an already accessible group.
          status:
            type: string
            optional: true
          severity:
            type: string
            optional: true
          from:
            type: string
            optional: true
          to:
            type: string
            optional: true
          staleDays:
            type: number
            optional: true
          actionableIssuesOnly:
            type: boolean
            optional: true
          cursor:
            type: string
            optional: true
            description: Opaque cursor from the previous response.
          limit:
            type: number
            optional: true
            description: 1-100, default 50.
        x-mcp:
          channel: portfolio
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: portfolio_agent_supervision_summary
        description: Return a snapshot-consistent health summary for scheduled agents and tasks across every accessible project. Includes task and execution states, stale runs, repeated blockers, current failures, start-delay and duration percentiles, trace completeness, pending human actions, safe coverage and partial failures.
        params:
          asOf:
            type: string
            optional: true
            description: Authoritative ISO instant shared with detail calls.
          timezone:
            type: string
            optional: true
            description: IANA timezone. Defaults to Europe/Madrid.
          from:
            type: string
            optional: true
            description: Execution window start. Defaults to 30 days before asOf; stale running executions remain visible.
          to:
            type: string
            optional: true
            description: Execution window end. Defaults to asOf and cannot exceed it.
          projectStatus:
            type: string
            enum:
            - active
            - inactive
            - all
            optional: true
          projectId:
            type: string
            optional: true
            description: May only narrow effective access.
          groupId:
            type: string
            optional: true
            description: May only narrow effective access.
          agentId:
            type: string
            optional: true
          taskStatus:
            type: string
            enum:
            - active
            - paused
            - completed
            optional: true
          executionStatus:
            type: string
            enum:
            - running
            - completed
            - failed
            - skipped
            - deferred
            optional: true
          staleRunningMinutes:
            type: number
            optional: true
            description: 5-43200, default 60.
          startDelayMinutes:
            type: number
            optional: true
            description: 1-43200, default 30.
          repeatedBlockerCount:
            type: number
            optional: true
            description: 2-20, default 2.
          manualInactivityDays:
            type: number
            optional: true
            description: 1-365, default 14.
        x-mcp:
          channel: portfolio
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: portfolio_agent_supervision_items
        description: Return cursor-paginated task supervision detail for the same snapshot and filters as the summary. Each item includes the compact current cycle and authoritative verification/decision references. Alerts include severity, reasonCode, safe evidence, age and recommendedHumanAction; equivalent parent/child alerts are deduplicated.
        params:
          asOf:
            type: string
            optional: true
            description: Reuse the exact summary asOf to obtain the same snapshotId.
          timezone:
            type: string
            optional: true
          from:
            type: string
            optional: true
          to:
            type: string
            optional: true
          projectStatus:
            type: string
            enum:
            - active
            - inactive
            - all
            optional: true
          projectId:
            type: string
            optional: true
          groupId:
            type: string
            optional: true
          agentId:
            type: string
            optional: true
          taskStatus:
            type: string
            enum:
            - active
            - paused
            - completed
            optional: true
          executionStatus:
            type: string
            enum:
            - running
            - completed
            - failed
            - skipped
            - deferred
            optional: true
          staleRunningMinutes:
            type: number
            optional: true
          startDelayMinutes:
            type: number
            optional: true
          repeatedBlockerCount:
            type: number
            optional: true
          manualInactivityDays:
            type: number
            optional: true
          cursor:
            type: string
            optional: true
            description: Opaque cursor bound to snapshotId and filters.
          limit:
            type: number
            optional: true
            description: 1-100, default 50.
        x-mcp:
          channel: portfolio
          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: portfolio
        effect: read
        requiredScope: read
        approval: none
        requestShape: tool_params
      operationId: postApiPortfolioAgentQuery
      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