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.
  • 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 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": "Production health check",
    "prompt": "Check production status and recent errors.",
    "triggerCondition": "Notify only if production is unhealthy.",
    "cronExpression": "*/15 * * * *",
    "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"
}

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'