digitalpublic-com Processes API

openapi: 3.2.0
info:
  title: DigitalPublic Agent Processes 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: Processes
paths:
  /api/agent/processes:
    post:
      summary: Verifiable process work queue
      description: Poll, start, claim and submit nodes in project-scoped versioned workflows. Agents complete nodes, but only DigitalPublic advances or finishes the process after deterministic verification.
      tags:
      - Processes
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - tool
              properties:
                tool:
                  type: string
                  enum:
                  - list_process_runs
                  - list_process_work
                  - start_process_run
                  - get_process_run
                  - claim_process_node
                  - resume_process_node
                  - heartbeat_process_node
                  - reconcile_sent_delivery
                  - postpone_process_human_wait
                  - submit_process_node_result
                  - list_process_crm_opportunities
                  - progress_process_crm_opportunity
                params:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Process operation succeeded.
        '409':
          description: Claim conflict, expired lease, invalid state, or workflow-managed operation.
      x-tools:
      - name: list_process_runs
        description: Read paginated project process history across all states with cycle dates, blockers, recorded verifier results and evidence. Does not execute work or run verification. Coverage declares recorded results only; use get_process_run for node details and list_process_work for contract-checked reconciliation candidates.
        params:
          taskId:
            type: string
            optional: true
          limit:
            type: number
            optional: true
            default: 50
          offset:
            type: number
            optional: true
            default: 0
        x-mcp:
          channel: processes
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_process_work
        description: List due process triggers, blockedTriggers with the exact open run that prevents a later schedule, prepared agent nodes, exact sentDeliveryReconciliations candidates and failedRunReconciliations for this project. Failed-run candidates link a verified delivery completed after the failure to close_process_run and preserve the original failure. The call safely reconciles expired reservations, invalidated delivery authorizations and unclaimed nodes pinned to an older task workflow version. A delivery candidate is only offered after project, period, audience, purpose, route, route-version, blueprint and report attachment checks pass.
        params: {}
        x-mcp:
          channel: processes
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: start_process_run
        description: Atomically start a due process task. Repeating the same scheduled trigger returns the same run. Manual processes require a stable idempotencyKey.
        params:
          taskId:
            type: string
            required: true
          idempotencyKey:
            type: string
            optional: true
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: get_process_run
        description: Read the pinned graph version, current state, node attempts, real verification evidence, events and blockers. Set compact=true to receive a small status and error summary without large node outputs.
        params:
          processRunId:
            type: string
            required: true
          compact:
            type: boolean
            optional: true
            description: Return status and node errors without large outputs or events.
        x-mcp:
          channel: processes
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: claim_process_node
        description: Atomically reconcile and reserve one prepared node for 30 minutes. Outdated unclaimed or blocked built-in workflow contracts fail closed or are recovered against the latest published version before claim, preserving prior evidence. Repeating the call for a live reservation owned by the same authenticated credential rotates the token and resumes that reservation without creating another attempt. Returns an opaque claimToken required for heartbeat and submission. A supervised-browser AGENT_TASK also returns a project-bound browserTask contract with the exact approved artifact hash, HTTPS start URL, fail-closed domain allowlist, stable execution id and stop conditions.
        params:
          nodeRunId:
            type: string
            required: true
          instructionVersion:
            type: string
            optional: true
            description: Required by workflows with instructionTraceRequired.
          instructionHash:
            type: string
            optional: true
            description: SHA-256 of the instruction sources used by the heartbeat.
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: resume_process_node
        description: Resume a still-active reservation owned by the same authenticated credential after local state loss. Atomically rotates the old token and returns a new token while preserving the node attempt and hard timeout.
        params:
          nodeRunId:
            type: string
            required: true
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: heartbeat_process_node
        description: Extend an active reservation by another 30 minutes without exceeding the node timeout.
        params:
          nodeRunId:
            type: string
            required: true
          claimToken:
            type: string
            required: true
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: reconcile_sent_delivery
        description: Adopt an authorized replacement email and attached report that already have verified SENT evidence. This operation is idempotent, never invokes the email transport, preserves previous resource ids and the reason in the process audit trail, and advances through the deterministic delivery verifier. It only accepts a run currently waiting at a human authorization gate and requires an exact project, period, audience, purpose, route, route-version and attachment match.
        params:
          processRunId:
            type: string
            required: true
          emailId:
            type: string
            required: true
            description: Replacement project email with SENT, sentAt, Message-ID and authorization evidence.
          reportId:
            type: string
            required: true
            description: Replacement authorized and sent report referenced by the email attachment.
          reason:
            type: string
            required: true
            description: Human-readable reason preserved in the immutable run event.
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: postpone_process_human_wait
        description: Postpone an external client or distributor HUMAN_WAIT until an exact follow-up instant. The governed operation is project-scoped and idempotent, keeps the run pinned to its workflow version and cycle, and never changes the task schedule or frequency. Internal team waits cannot be postponed.
        params:
          processRunId:
            type: string
            required: true
          followUpAt:
            type: string
            required: true
            description: Future ISO instant, up to 366 days.
          reason:
            type: string
            required: true
          idempotencyKey:
            type: string
            required: true
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: submit_process_node_result
        description: Submit structured node success or failure with evidence. A supervised-browser task requires evidence.browserTask matching the reservation, approved hash, final allowed URL, completion time and stop condition; stopped executions cannot report success. A technical failure creates another bounded attempt while maxAttempts remain; only after exhaustion does DigitalPublic follow the failure edge. A structurally successful AGENT_TASK whose output declares operationalOutcome=BLOCKED follows the failure edge immediately without consuming technical retries, so a contractual HUMAN_WAIT can open. This completes only the claimed node.
        params:
          nodeRunId:
            type: string
            required: true
          claimToken:
            type: string
            required: true
          idempotencyKey:
            type: string
            required: true
          result:
            type: string
            required: true
            enum:
            - success
            - failure
          output:
            type: object
            optional: true
          evidence:
            type: object
            optional: true
            description: Typed evidence may reference REPORT, EMAIL, URL, or PLATFORM_OPERATION. A platform operation must be SUCCEEDED.
          usedTools:
            type: array
            optional: true
            description: Exact registered tool names used by this node; every value must be allowed by the pinned workflow.
          errorMessage:
            type: string
            optional: true
          humanSummary:
            type: string
            optional: true
            description: Human-readable Markdown/GFM summary, maximum 1,000 characters.
          technicalDetails:
            type: string
            optional: true
            description: Optional technical Markdown/GFM detail kept separate from the human summary.
          resourceReferences:
            type: array
            optional: true
            description: 'Typed DigitalPublic resources: [{resourceType,resourceId}]. IDs are validated in the authenticated project.'
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: list_process_crm_opportunities
        description: Read project CRM opportunities for a claimed workflow node using explicit filters. Returns limited fields and a bounded page.
        params:
          nodeRunId:
            type: string
            required: true
          claimToken:
            type: string
            required: true
          queue:
            type: string
            optional: true
            enum:
            - pending
            - in_progress
            - finished
            - spam
          stage:
            type: string
            optional: true
          type:
            type: string
            optional: true
          tag:
            type: string
            optional: true
          source:
            type: string
            optional: true
          q:
            type: string
            optional: true
          ownerUserId:
            type: string
            optional: true
          nextActionBefore:
            type: string
            optional: true
          limit:
            type: number
            optional: true
          offset:
            type: number
            optional: true
        x-mcp:
          channel: processes
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: progress_process_crm_opportunity
        description: Progress one CRM opportunity in a claimed workflow node after a successful human checkpoint. Requires expected stage and stable idempotency key; stores CRM interaction and process event atomically.
        params:
          nodeRunId:
            type: string
            required: true
          claimToken:
            type: string
            required: true
          leadId:
            type: string
            required: true
          expectedStage:
            type: string
            required: true
          stage:
            type: string
            required: true
          note:
            type: string
            required: true
          idempotencyKey:
            type: string
            required: true
          nextActionAt:
            type: string
            optional: true
          nextActionNote:
            type: string
            optional: true
        x-mcp:
          channel: processes
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      operationId: postApiAgentProcesses
      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