Automations API

Automations run bounded Agent Y2 instructions on a schedule or after a selected profile report. Definitions and runs remain owner-private inside the API key workspace.

Scopes and availability

Automations and both API scopes require Pro or Elite. The same workspace definition limits, entitlement checks, overlap policy, and shared Agent Y2 credit admission used by the application also apply to API requests.

Create a scheduled Automation

curl -sS "https://api.y2.dev/api/v1/automations" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: automation-daily-watch-2026-07" \
  -d '{
    "name": "Daily supply chain watch",
    "instructions": "Summarize material changes and cite the strongest evidence.",
    "projectId": "prj_0123456789abcdef01234567",
    "trigger": {
      "kind": "schedule",
      "frequency": "daily",
      "timeOfDay": "13:00",
      "timezone": "America/Chicago"
    },
    "notificationPolicy": "failures_only",
    "status": "active"
  }'

For a report-completion trigger, use:

{
  "kind": "profile_report_completed",
  "profileId": "prf_0123456789abcdef01234567"
}

Inspect and update

Use GET /api/v1/automations, GET /api/v1/automations/{automationId}, and GET /api/v1/automations/{automationId}/runs. List responses are bounded to 50 rows per request. Definition and run-history collections return the standard opaque nextCursor and links.next fields for complete traversal.

PATCH /api/v1/automations/{automationId} accepts definition fields or a status-only lifecycle change. An archived Automation cannot be edited or resumed. Send the latest ETag in If-Match when coordinating multiple writers.

Request a manual run

curl -sS -X POST "https://api.y2.dev/api/v1/automations/$AUTOMATION_ID/runs" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Idempotency-Key: manual-run-2026-07-24T1500Z"

The endpoint returns 202 Accepted. The idempotency key is required and prevents duplicate admission for retries. Poll the run-history endpoint for queued, running, terminal, usage, and billing state.