digitalpublic-com Agent API

openapi: 3.2.0
info:
  title: DigitalPublic Agent 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: Agent
paths:
  /api/agent/knowledge-review/agent-query:
    post:
      summary: Project and vault bounded knowledge review
      x-tools:
      - name: list_supervision_entries
        description: Complete paginated supervision inventory of diaries, human contributions from all registrars, and proposals in authorized vaults. Includes origin, registrar, author, phase, evidence, conflicts and explicit scope/coverage. Outside the scope remains unknown.
        params:
          query:
            type: string
            optional: true
          vaultId:
            type: string
            optional: true
          projectId:
            type: string
            optional: true
          kind:
            type: string
            optional: true
          state:
            type: string
            optional: true
          provenance:
            type: string
            optional: true
          actorId:
            type: string
            optional: true
          authorId:
            type: string
            optional: true
          confirmerId:
            type: string
            optional: true
          since:
            type: string
            optional: true
          until:
            type: string
            optional: true
          cursor:
            type: string
            optional: true
          limit:
            type: integer
            optional: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:review
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_supervision_entry
        description: Read the immutable original, provenance, evaluation and proposals of an entry in authorized supervisory vaults, including historical diaries and other registrars' human contributions.
        params:
          entryId:
            type: string
            required: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:review
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_pending_reviews
        description: List paginated review summaries across authorized vaults. Global reviewers can supervise all active vaults; project/group reviewers use enabled vault bindings. Optional vaultId/projectId filters narrow the queue. Never decide automatically.
        params:
          vaultId:
            type: string
            optional: true
          projectId:
            type: string
            optional: true
            description: Optional origin-project filter within the current administrative scope.
          documentType:
            type: string
            optional: true
          reviewGroupId:
            type: string
            optional: true
          statuses:
            type: array
            optional: true
          maxAgeDays:
            type: integer
            optional: true
          limit:
            type: integer
            optional: true
          cursor:
            type: string
            optional: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:review
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_review
        description: Read current/proposed content, differences, evidence, canonical revision id, exact snapshot hash and decision history. CHANGES_REQUESTED proposals offer individual rejection with a required explanation to close an obsolete proposal; no canonical content is changed.
        params:
          proposalId:
            type: string
            required: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:review
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_review_group
        description: Read every member of an atomic review group and its exact snapshot hash.
        params:
          reviewGroupId:
            type: string
            required: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:review
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      tags:
      - Agent
      operationId: postApiAgentKnowledgeReviewAgentQuery
      x-operation-id-source: derived
  /api/agent/knowledge-review/agent-mutate:
    post:
      summary: Project and vault bounded human-attested knowledge decisions
      x-tools:
      - name: mark_human_origin_pending
        description: Record a human-directed intake's official provenance reference, preserving the raw original. Without a linked contribution, leaves explicit pending attribution; never invents an author or confirmation. Optional contribution must match entry vault/project and current permissions. Exact retries are idempotent.
        params:
          entryId:
            type: string
            required: true
          expectedOriginalHash:
            type: string
            required: true
          reference:
            type: string
            required: true
          contributionId:
            type: string
            optional: true
        x-mcp:
          channel: knowledge
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:approve
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: prepare_review_decision
        description: Freeze exactly one proposal OR group, decision and explanation for five minutes. Present the returned reviewUrl to the human BEFORE asking for confirmation, together with the decision, scope and expiry. The authenticated URL shows the exact frozen current/proposed content and differences. Wait for explicit human instruction before confirming. No document is applied. Approval must be completed by an authenticated human through the review URL.
        params:
          proposalId:
            type: string
            optional: true
          reviewGroupId:
            type: string
            optional: true
          decision:
            type: string
            required: true
            enum:
            - approve
            - reject
            - request_changes
          note:
            type: string
            optional: true
            description: Required for rejection or changes requested.
          idempotencyKey:
            type: string
            required: true
        x-mcp:
          channel: knowledge
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:approve
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: confirm_review
        description: Approval through an agent code is denied; direct the human to the authenticated review URL. For rejection or requesting changes, use the single-use code only AFTER presenting reviewUrl and receiving explicit human instruction. No autonomous or policy approval. This attests the agent credential and its claim of human consent, NOT cryptographic human identity. Changed, expired, incorrect or reused challenges fail.
        params:
          challengeId:
            type: string
            required: true
          confirmationCode:
            type: string
            required: true
          idempotencyKey:
            type: string
            required: true
        x-mcp:
          channel: knowledge
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          additionalScopes:
          - knowledge:approve
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      tags:
      - Agent
      operationId: postApiAgentKnowledgeReviewAgentMutate
      x-operation-id-source: derived
  /api/agent/knowledge-clarifications/agent-query:
    post:
      summary: Participant private priority knowledge inbox
      x-tools:
      - name: list_clarification_participants
        description: List currently authorized recipient people and agents separately for an exact proposal. Requires reviewer authority. Original human authorship remains explicit or unknown; an agent name never identifies a human.
        params:
          proposalId:
            type: string
            required: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_clarifications
        description: Consult your private priority inbox at start/resume and according to each thread pollMinutes during activity. Persists consultation evidence. Does not attest receipt, human response or host availability. Follow every cursor. Participants and current vault/project grants are required. Inform your responsible human; perform no business action or approval.
        params:
          idempotencyKey:
            type: string
            required: true
            description: Stable key reused only for the same exact request.
          cursor:
            type: string
            optional: true
          limit:
            type: integer
            optional: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_clarification
        description: Read an authorized private clarification thread, immutable request version/hash, separately identified human author, registrar, participants, receipts, responses and resolution history.
        params:
          threadId:
            type: string
            required: true
        x-mcp:
          channel: knowledge
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      tags:
      - Agent
      operationId: postApiAgentKnowledgeClarificationsAgentQuery
      x-operation-id-source: derived
  /api/agent/knowledge-clarifications/agent-mutate:
    post:
      summary: Participant bounded private knowledge discussion
      x-tools:
      - name: open_clarification
        description: Persist a question on an exact proposal version without changing its review status. Requires current review authority. Explicit recipient userId and agentId are separate participants; never infer a person from agent name. Validates recipients' current vault/project rights. Creates durable internal priority inbox availability; sends no external message.
        params:
          idempotencyKey:
            type: string
            required: true
            description: Stable key reused only for the same exact request.
          proposalId:
            type: string
            required: true
          expectedVersion:
            type: integer
            required: true
          expectedHash:
            type: string
            required: true
          content:
            type: string
            required: true
          requesterUserId:
            type: string
            optional: true
            description: Explicit human requester also listed as REVIEWER; requires humanReference and current review authority.
          humanReference:
            type: string
            optional: true
          reviewEventId:
            type: string
            optional: true
            description: Existing REQUEST_CHANGES event; question must preserve its original note and target.
          participants:
            type: array
            required: true
            description: '[{userId OR agentId, role: RESPONDER|RESPONSIBLE|REVIEWER}]; at least one responder.'
          policy:
            type: object
            optional: true
            description: reminderMinutes 60..43200 (1440), maxReminders 0..5 (3), escalationMinutes 60..86400 (4320), pollMinutes 5..1440 (30).
        x-mcp:
          channel: knowledge
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: update_clarification
        description: Record explicit receipt, response, treatment/blocking, reviewer resolution or policy. Receipt never means response. A response may link a real successor proposal; approval of its exact version remains separate. attributedUserId plus humanReference records a relayed human authorship claim, not authenticated human approval. Use current revision and stable idempotency key; never autonomously impersonate a human.
        params:
          threadId:
            type: string
            required: true
          idempotencyKey:
            type: string
            required: true
            description: Stable key reused only for the same exact request.
          expectedRevision:
            type: integer
            required: true
          action:
            type: string
            required: true
            enum:
            - receive
            - respond
            - resolve
            - configure
            - block
          content:
            type: string
            optional: true
          attributedUserId:
            type: string
            optional: true
          humanReference:
            type: string
            optional: true
          proposalId:
            type: string
            optional: true
          policy:
            type: object
            optional: true
        x-mcp:
          channel: knowledge
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: add_clarification_participants
        description: Add currently authorized people or agents to an existing unresolved thread without replacing its request, version, hash, events or current participants. Requires a reviewer participant and the current thread revision. Association between an agent and a person does not grant access; each added identity is authorized independently.
        params:
          threadId:
            type: string
            required: true
          idempotencyKey:
            type: string
            required: true
            description: Stable key reused only for the same exact request.
          expectedRevision:
            type: integer
            required: true
          participants:
            type: array
            required: true
            description: 'New [{userId OR agentId, role: RESPONDER|RESPONSIBLE|REVIEWER}] identities.'
        x-mcp:
          channel: knowledge
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      tags:
      - Agent
      operationId: postApiAgentKnowledgeClarificationsAgentMutate
      x-operation-id-source: derived
components:
  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