Skip to main content

Agent Automations API

The Agent Automations API lets you manage the same scheduled agent automations that are available in the Quave ONE dashboard: list options, create or edit automations, pause/resume, delete, run once, and inspect run history.

Make sure to read the Get Started document to understand authentication and base URLs.

Security and validation​

  • All endpoints require account membership for accountId.
  • Automations are private to the user who created them; account membership does not expose another user's automations.
  • Create and update use the same backend validation as the UI: cron expression validation, enabled MCP key ownership, accessible LLM provider key checks, contact point ownership checks, and delivery-mode validation.
  • New and updated automations with deliveryMode: "on-trigger" require a non-empty triggerCondition; this prevents saving an empty conditional-notification setup. Existing legacy records remain readable so owners can repair them in the dashboard.
  • When called by MCP, the selected automation MCP key must have the same or fewer scopes than the calling MCP key. This prevents a limited MCP key from creating or inspecting automations that use a more powerful MCP key.
  • Run lists return summary metadata only. Use the single-run endpoint for transcripts and step details.
  • includeToolResults=true for run details can expose sensitive tool output, records a secret-decrypt audit event, and requires quave:read:secrets for MCP callers.

List agent library profiles​

GET /agent/profiles?accountId=ACC_ID returns the full library catalog with per-account eligibility and account-wide enabled state. Each profile includes publishedAt, the publication timestamp of its current published revision. To suggest the latest unused profiles, filter for eligible profiles with no enabledAutomation, sort by publishedAt descending, then take the desired number of results. The endpoint itself does not limit the catalog.

List create/edit options​

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/automation-options?accountId=ACC_ID'

Returns enabled MCP key metadata, accessible LLM provider key metadata, contact points, delivery modes, run statuses, trigger sources, and cron presets. It never returns key plaintext.

Create an automation​

curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "ACC_ID",
    "name": "Actionable production anomaly watcher",
    "prompt": "Compare the last hour of production with the seven-day baseline. Trigger only when the finding has current impact, an evidence-backed immediate action, and a measurable recovery check.",
    "triggerCondition": "Notify only for a new or escalated actionable production anomaly. Do not trigger on relative delta alone or a low-volume new error signature.",
    "cronExpression": "0 * * * *",
    "timezone": "UTC",
    "mcpKeyId": "MCP_KEY_ID",
    "llmProviderKeyId": "LLM_PROVIDER_KEY_ID",
    "deliveryMode": "on-trigger",
    "contactPointIds": ["CONTACT_POINT_ID"],
    "enabled": true
  }' \
  https://api.quave.cloud/api/public/v1/agent/automation

Response:

{
  "automationId": "AUTOMATION_ID",
  "message": "Automation created successfully"
}

Fallback model​

With your own OpenRouter or OpenAI-compatible provider key, you can set an optional fallbackModelId. Automation runs give each model request up to 4 minutes. When a request runs past that, the single retry asks fallbackModelId instead of repeating the same slow request. To clear it, send an empty string on update. The saved value is returned as llmFallbackModelId.

A failed run still reports the tokens, tool calls, cost, and steps it completed before the failure.

For a production-ready prompt with absolute metric and error-volume floors, deploy correlation, 24-hour deduplication, and a concise incident handoff, use the actionable anomaly watcher guide.

List automations​

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/automations?accountId=ACC_ID&limit=50&sortBy=createdAt'

sortBy can be createdAt, lastRunAt, or name.

Get an automation​

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/automation?accountId=ACC_ID&automationId=AUTOMATION_ID'

Update an automation​

Send only the fields to change. Omitted fields are merged with the existing automation and then validated with the same backend logic used by the UI.

curl -X PATCH \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "ACC_ID",
    "automationId": "AUTOMATION_ID",
    "cronExpression": "0 * * * *",
    "enabled": true
  }' \
  https://api.quave.cloud/api/public/v1/agent/automation

Toggle or delete​

curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "accountId": "ACC_ID", "automationId": "AUTOMATION_ID", "enabled": false }' \
  https://api.quave.cloud/api/public/v1/agent/automation/toggle
curl -X DELETE \
  -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/automation?accountId=ACC_ID&automationId=AUTOMATION_ID'

Run once and inspect runs​

curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "accountId": "ACC_ID", "automationId": "AUTOMATION_ID" }' \
  https://api.quave.cloud/api/public/v1/agent/automation/run-once

Response includes jobId, which can be used to poll the resulting run:

{ "ok": true, "jobId": "JOB_ID" }

List runs:

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/automation-runs?accountId=ACC_ID&automationId=AUTOMATION_ID&limit=20'

Get one run by runId or jobId:

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/automation-run?accountId=ACC_ID&jobId=JOB_ID&includeSteps=true'