digitalpublic-com Project Worker API

openapi: 3.2.0
info:
  title: DigitalPublic Agent Project Worker 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: Project Worker
paths:
  /api/project-worker/agent-query:
    post:
      summary: Read one fenced project worker context
      description: Returns only the exact work attached to the signed dispatch for the authenticated host.
      x-tools:
      - name: preview_run_now
        description: Preview explicit overdue project tasks and their active external descendants, effective policy and delivery blockers. Requires administrative project:dispatch scope. No business work is executed.
        params:
          projectId:
            type: string
            required: true
          taskIds:
            type: array
            required: true
        x-mcp:
          channel: project
          effect: read
          requiredScope: write
          approval: none
          requestShape: tool_params
          additionalScopes:
          - project:dispatch
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: dispatch_status
        description: Read the exact project dispatch, linked native execution, delivery attempts and verified work results.
        params:
          projectId:
            type: string
            required: true
          dispatchId:
            type: string
            required: true
        x-mcp:
          channel: project
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_context
        description: Re-read the exact project and task state of a live fenced dispatch without widening its scope.
        params:
          dispatchId:
            type: string
            required: true
          fencingToken:
            type: number
            required: true
        x-mcp:
          channel: project
          effect: read
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: INLINE
            resourceClass: LIGHT
            priority: INTERACTIVE
            costModel: FIXED
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_readiness_document
        description: Read one exact document from the current canonical readiness package for this fenced worker generation.
        params:
          workerId:
            type: string
            required: true
          workerGeneration:
            type: number
            required: true
          path:
            type: string
            required: true
        x-mcp:
          channel: project
          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: project
        effect: read
        requiredScope: read
        approval: none
        requestShape: tool_params
      tags:
      - Project Worker
      operationId: postApiProjectWorkerAgentQuery
      x-operation-id-source: derived
  /api/project-worker/agent-mutate:
    post:
      summary: Run one fenced project worker dispatch
      description: Claims, completes or fails only the signed dispatch assigned to this host.
      x-tools:
      - name: run_now
        description: Materialize one official dispatch outside the operating window without changing recurring schedules. Only after an explicit human instruction authorizing the exact preview, supply its previewHash and humanInstructionReference. Business actions retain their independent approvals. Reuse idempotencyKey on retries and follow dispatch_status; pending delivery never proves completion.
        params:
          projectId:
            type: string
            required: true
          taskIds:
            type: array
            required: true
          previewHash:
            type: string
            required: true
          idempotencyKey:
            type: string
            required: true
          humanInstructionReference:
            type: string
            required: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          additionalScopes:
          - project:dispatch
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_prepare
        description: Prove from the child conversation that the project worker contract is available without executing business work.
        params:
          workerId:
            type: string
            required: true
          workerGeneration:
            type: number
            required: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_ready
        description: Confirm readiness with exact revision and SHA-256 evidence for the canonical instruction and every unconditional document dependency it declares.
        params:
          workerId:
            type: string
            required: true
          workerGeneration:
            type: number
            required: true
          contractVersion:
            type: string
            required: true
          vaultSlug:
            type: string
            required: true
          instructionPath:
            type: string
            required: true
          instructionRevision:
            type: number
            optional: true
          instructionSha256:
            type: string
            required: true
          documentEvidence:
            type: array
            required: true
            description: Every document returned by worker_prepare, each with path, revision and sha256.
        x-mcp:
          channel: project
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_readiness_failed
        description: Record a transient or blocking readiness failure reported by the child conversation.
        params:
          workerId:
            type: string
            required: true
          workerGeneration:
            type: number
            required: true
          transient:
            type: boolean
            required: true
          errorCode:
            type: string
            required: true
          errorDetail:
            type: string
            required: true
          retryAfterSeconds:
            type: number
            optional: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: legacy_prepare
        description: Start a read-only continuity check from an active legacy project conversation.
        params:
          workerId:
            type: string
            required: true
          workerGeneration:
            type: number
            required: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: legacy_ready
        description: Confirm that an active legacy conversation can read the complete canonical authority chain.
        params:
          workerId:
            type: string
            required: true
          workerGeneration:
            type: number
            required: true
          contractVersion:
            type: string
            required: true
          vaultSlug:
            type: string
            required: true
          instructionPath:
            type: string
            required: true
          instructionRevision:
            type: number
            optional: true
          instructionSha256:
            type: string
            required: true
          documentEvidence:
            type: array
            required: true
            description: Every document returned by legacy_prepare, each with path, revision and sha256.
        x-mcp:
          channel: project
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: legacy_readiness_failed
        description: Record a transient or blocking continuity failure from an active legacy conversation.
        params:
          workerId:
            type: string
            required: true
          workerGeneration:
            type: number
            required: true
          transient:
            type: boolean
            required: true
          errorCode:
            type: string
            required: true
          errorDetail:
            type: string
            required: true
          retryAfterSeconds:
            type: number
            optional: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: read
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_claim
        description: Claim the signed dispatch inside its permanent project conversation and read the exact offered work.
        params:
          dispatchId:
            type: string
            required: true
          fencingToken:
            type: number
            required: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_renew
        description: Renew a live fenced project execution before its lease expires.
        params:
          dispatchId:
            type: string
            required: true
          fencingToken:
            type: number
            required: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_complete
        description: Complete a fenced project dispatch with a verifiable result for every offered work item.
        params:
          dispatchId:
            type: string
            required: true
          fencingToken:
            type: number
            required: true
          status:
            type: string
            enum:
            - COMPLETED
            - SKIPPED
            optional: true
          nativeTurnId:
            type: string
            optional: true
          workResults:
            type: array
            required: true
            description: 'One result per offered task: taskId, outcome (COMPLETED, BLOCKED, DEFERRED, ALREADY_RESOLVED, SKIPPED), agentTaskExecutionId or processRunId. SKIPPED requires humanInstructionReference and reason and must omit execution references; it records an authorized exclusion without executing or rescheduling the task.'
        x-mcp:
          channel: project
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: worker_fail
        description: Fail a fenced project dispatch with a classification and evidence for every offered work item.
        params:
          dispatchId:
            type: string
            required: true
          fencingToken:
            type: number
            required: true
          nativeTurnId:
            type: string
            optional: true
          errorCode:
            type: string
            optional: true
          errorDetail:
            type: string
            optional: true
          workResults:
            type: array
            required: true
            description: 'One result per offered task: taskId, outcome (COMPLETED, BLOCKED, DEFERRED, ALREADY_RESOLVED, SKIPPED), agentTaskExecutionId or processRunId. SKIPPED requires humanInstructionReference and reason and must omit execution references; it records an authorized exclusion without executing or rescheduling the task.'
        x-mcp:
          channel: project
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      - name: schedule_override
        description: Temporarily intensify one project routine with a mandatory reason and expiry.
        params:
          projectId:
            type: string
            required: true
          taskId:
            type: string
            required: true
          startsAt:
            type: string
            optional: true
          expiresAt:
            type: string
            required: true
          nextRunAt:
            type: string
            optional: true
          scheduleRule:
            type: object
            optional: true
          reason:
            type: string
            required: true
          exitCondition:
            type: string
            optional: true
        x-mcp:
          channel: project
          effect: write
          requiredScope: write
          approval: none
          requestShape: tool_params
          workload:
            executionMode: AUTO
            resourceClass: STANDARD
            priority: NORMAL
            costModel: ITEMS
            idempotencyMode: READ_BEFORE_WRITE
      x-mcp:
        channel: project
        effect: write
        requiredScope: write
        approval: none
        requestShape: tool_params
      tags:
      - Project Worker
      operationId: postApiProjectWorkerAgentMutate
      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