Automations, Routines and publishing
Read and configure Automate settings, run technical audits, read recurring Routine state and request confirmed, draft-only CMS delivery.
Automate control and technical audits
Section titled “Automate control and technical audits”Release status: implementation pending deployment. These routes become available with the native technical audit automation release.
All paths use /api/agent/v1. Existing /routines readers remain compatible. A credential needs the new routines:write scope to manage settings; existing OAuth connections must reconnect and approve that permission. Read permission alone never allows a settings change.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /clients/:client_id/automations |
routines:read |
List all supported Automate workflows and explicit unavailable states |
| GET | /clients/:client_id/automations/:type |
routines:read |
Read one workflow’s settings and bounded history |
| PUT | /clients/:client_id/automations |
routines:write |
Confirm and save exact workflow settings |
| POST | /clients/:client_id/automations/technical_site_audit/run |
routines:write, site-auditor:write |
Confirm one audit using the saved scope |
| GET | /clients/:client_id/automations/technical_site_audit/runs/:run_id/handoff |
routines:read, site-auditor:read |
Read completed technical-only findings and an agent prompt |
Types are technical_site_audit, content, knowledge_monitor, brand_mentions, google_reviews, and yelp_reviews. Settings changes use the existing workflow handlers, including their ownership, provider availability, plan capacity, source eligibility and destination validation. There is no arbitrary workflow builder.
PUT /clients/:client_id/automations
Section titled “PUT /clients/:client_id/automations”PUT /api/agent/v1/clients/:client_id/automations
Requires confirm_update: true and an Idempotency-Key header (8–128 characters: letters, digits, underscores, dots, colons and dashes). Read settings first; preserve fields that were not requested to change. A content update supplies automationId; omit it to create a schedule. Other types have one configuration per client or their existing location settings.
Technical audit example after reading the current client domain and version:
{ "type": "technical_site_audit", "confirm_update": true, "settings": { "enabled": true, "frequency": "weekly", "weekday": 1, "hourUtc": 9, "maxPages": 100, "maxDepth": 10, "expectedVersion": 0, "expectedDomain": "example.com" }}Weekly UTC scheduling is explicit: weekdays are Sunday 0 through Saturday 6; hours are 0 through 23. Page limits accept integers 1–1000, depth 1–50. The defaults are weekly, Monday at 09:00 UTC, 100 pages and depth 10. Use the returned version as expectedVersion and clientDomain as expectedDomain; stale values return 409. Respect for robots.txt is fixed on; external-link checking is off. Enabling authorizes future recurring usage but never starts an immediate crawl. Editing page/depth limits preserves the next occurrence; enabling or changing timing computes the next future occurrence. Pausing prevents future admissions and preserves reports; already-admitted crawls finish through Site Auditor.
Content settings accept enabled, destination (projects, wordpress, webflow, github), frequency (daily, weekly, monthly), nullable dayOfWeek/dayOfMonth, topics (up to 100), postStatus (draft, publish), language, languageSource (user, auto, default) and trackPerformance. New content schedules require an explicit destination and enabled decision. Knowledge settings require an explicit enabled decision and accept frequency (weekly, monthly) and eligible sourceIds. Brand settings require phrase, enabled, emailDigest and optional bounded mustIncludeOne/cannotIncludeAny arrays. Google reviews require enabled, owned locationIds, mode (ask, auto) and optional triageEnabled. Yelp requires enabled with optional owned locationId or url; its existing validation applies. Enabling existing content or Google auto-reply workflows retains their selected future publishing behavior. The technical audit handoff always remains draft-only.
An exact retry with the same key returns the saved settings receipt. Reusing a key for different settings returns 409. An interrupted legacy settings write with no confirmed receipt returns 409 outcome_unconfirmed; read current settings and reconcile before requesting another write. Do not retry an uncertain creation with a new key automatically.
POST /clients/:client_id/automations/technical_site_audit/run
Section titled “POST /clients/:client_id/automations/technical_site_audit/run”POST /api/agent/v1/clients/:client_id/automations/technical_site_audit/run
Read the saved settings, show GET /usage/estimate?operation=site_audit_run&max_pages=100 (using the saved ceiling), then send { "confirm_run": true } with a stable Idempotency-Key. The response contains the run id, state and projectId when admitted. state: failed or skipped means no new crawl started; inspect error. A settings save alone starts no work.
Saved automation reports cannot be re-crawled in place; use this run endpoint to create a new historical capture. Explicit partial-report continuation and triage remain available through Site Auditor. Each occurrence atomically records a new canonical Site Auditor project, allowance admission, durable crawl job and run receipt. Retries cannot purchase the same occurrence twice. Missed weeks coalesce into one due occurrence; they do not create a paid catch-up backlog. If an automation crawl is active, the next admission is skipped with a history receipt. Failed scheduled admissions remain in history and advance to the next week; fix the underlying issue and use an approved manual run when needed. Normal Site Auditor allowance, billing and worker recovery rules apply.
GET /clients/:client_id/automations/:type
Section titled “GET /clients/:client_id/automations/:type”GET /api/agent/v1/clients/:client_id/automations/:type
offset defaults to 0 and is capped at 100000. Technical audit history is 20 rows per page; content schedule summaries are 100 per page. Topic bodies are omitted from these summaries; use the existing Routine reader for one schedule’s paginated topics when needed. Omitted content settings are preserved by the canonical update handler. Follow pagination.hasMore. History includes the canonical report status, pages crawled, saved coverage, trigger, settings snapshot and admission failures. A page ceiling is not proof that all pages were reached. Report deletion leaves the occurrence receipt with an unavailable report reference; deleting the client removes its client-scoped automation records.
GET /clients/:client_id/automations/technical_site_audit/runs/:run_id/handoff
Section titled “GET /clients/:client_id/automations/technical_site_audit/runs/:run_id/handoff”GET /api/agent/v1/clients/:client_id/automations/technical_site_audit/runs/:run_id/handoff
Only completed saved reports qualify (409 otherwise). Findings are limited to 100 per page; follow pagination.hasMore with offset. The response includes totalTechnicalFindings, excludedFindings, coverage, prompt, unavailableChecks and draft-only restrictions. An explicit issue-type allowlist excludes content and unknown future categories. Evidence excludes editorial titles, descriptions and anchor text. A finding signals an investigation; it does not establish that a canonical, robots or redirect setting is wrong.
The native audit does not start Codex, Claude or another external agent. The member copies the prompt or their connected agent calls automation_audit_handoff. Repository/CMS access and browser validation remain separate. No PR, merge, CMS publication or deployment is performed by the schedule. New content, page copy, titles, descriptions, heading wording, alt text, editorial links, URL keyword rewrites and new schema facts are excluded from the technical fix handoff.
MCP tools are automation_list, automation_get, automation_update, automation_audit_run, and automation_audit_handoff. Serena exposes get_automations and an exact propose_configure_automation approval card. Serena’s authenticated client and organization define the scope; model arguments cannot change that identity. Both approval buttons and typed approval use the same durable claim and receipt. The serena:ask API remains read-only and cannot approve these changes.
Routines and publishing
Section titled “Routines and publishing”GET /clients/:client_id/routines combines recurring content Routines and Knowledge-monitor Routines. Filter with type=all|content|knowledge_monitor and optional enabled=true|false; limit is capped at 100 and offset at 10,000. GET /clients/:client_id/routines/:routine_id returns one Routine and paginates its current content topics or monitored source IDs. It reports counts for suggested and previously published topics without returning those historical topic bodies.
GET /clients/:client_id/publishing/connections returns connection status, credential-free safe target identity, capabilities, requirements, and verification freshness. Legacy connection targets remain null because their destination identity is stored with encrypted credentials. No credential material is returned.
For a first-time draft delivery, use the three-step workflow below. Use a stable, non-secret Idempotency-Key on both POST requests.
POST /clients/:client_id/publishing/artifactswithconnection_idandcopywriter_project_id. This creates or reuses the exact immutable destination-specific article snapshot. It does not create a CMS item or GitHub pull request.GET /clients/:client_id/publishing/preflight?connection_id=...&artifact_id=...&operation=create&requested_state=draft. Stop ifreadyis false. For GitHub, retain the returnedpreview.previewHashafter reviewing the safe path and repository details.POST /clients/:client_id/publishing/deliverieswith the same connection and artifact IDs,operation: "create",requested_state: "draft", andconfirm_delivery: true. GitHub also requiresexpected_preview_hash. The endpoint creates only a destination draft or reviewable pull request and returns a durable delivery ID.
MCP mirrors this stable API workflow as publishing_prepare_artifact, publishing_preflight, and publishing_request_draft_delivery. The MCP tools forward the idempotency key, fixed draft-only state, explicit confirmation, and GitHub preview hash to these Agent API routes; they do not duplicate destination logic or expose a live-publishing operation.
GET /clients/:client_id/publishing/deliveries lists delivery receipts and supports bounded pagination plus status and destination filters. GET /clients/:client_id/publishing/deliveries/:delivery_id returns preflight and validation defect categories, source currency, safe HTTP(S) remote identity, and validation state. It omits defect messages, evidence summaries, article bodies, and diagnostic messages.
The read routes are observational only. They cannot change or run a Routine, test or reconnect a destination, expose credentials or article bodies, validate a remote item, or retry a delivery. The two publishing:write routes are limited to internal snapshot creation and explicitly confirmed draft delivery; neither can request a live state.
