---
title: "Automations, Routines and publishing"
description: "Read and configure Automate settings, run technical audits, read recurring Routine state and request confirmed, draft-only CMS delivery."
canonical_url: "https://developers.rankability.com/guides/routines-and-publishing"
section: "Guides"
last_updated: 2026-11-14
---

# 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

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

`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:

```json
{
  "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

`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

`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

`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

`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.

1. `POST /clients/:client_id/publishing/artifacts` with `connection_id` and `copywriter_project_id`. This creates or reuses the exact immutable destination-specific article snapshot. It does not create a CMS item or GitHub pull request.
2. `GET /clients/:client_id/publishing/preflight?connection_id=...&artifact_id=...&operation=create&requested_state=draft`. Stop if `ready` is false. For GitHub, retain the returned `preview.previewHash` after reviewing the safe path and repository details.
3. `POST /clients/:client_id/publishing/deliveries` with the same connection and artifact IDs, `operation: "create"`, `requested_state: "draft"`, and `confirm_delivery: true`. GitHub also requires `expected_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.
