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 availabilityCopy Anchor Link

Automations and both API scopes require Pro or Elite. API requests use the app's workspace limits, permissions, overlap rules, and Agent Y2 credits.

Create a scheduled AutomationCopy Anchor Link

Replace projectId with an accessible Project ID, or omit it for an Automation without a Project.

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 updateCopy Anchor Link

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 runCopy Anchor Link

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.