Automations

A automation is a batch of AI posts generated at once and auto-scheduled across a posting window. You set a cadence (posts per day, for how many days), Viraloop generates one post per slot using the workspace's brand context, you review the batch, and launching turns every post into a scheduled post at its slot. Automation endpoints need the automations:read and automations:write scopes.

Lifecycle

draft -> generating -> review -> active -> completed or cancelled

Quota

The monthly automation quota depends on the plan. GET /automations returns it alongside the list:

{
	"quota": {
		"monthlyLimit": 8,
		"usedThisMonth": 2,
		"remaining": 6
	}
}

Once the quota is used up, starting another automation fails with error type usage_limit_reached; see errors and rate limits.

curl -s "https://viraloop.io/api/v1/automations" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

viraloop automations list --json

1. Create

POST /automations creates the automation in draft (scope automations:write, supports the Idempotency-Key header). Only name is required; everything else can be set now or later via PATCH:

curl -s -X POST "https://viraloop.io/api/v1/automations" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "July launch week",
    "cadence": { "postsPerDay": 2, "lengthDays": 7, "timezone": "America/New_York" },
    "selectedAccounts": { "tiktok": ["665f1b2a9c31a2b3c4d5e700"] }
  }'

viraloop automations create --name "July launch week" --posts-per-day 2 --length-days 7 \
  --timezone America/New_York --accounts tiktok:<accountId> --json

2. Generate

POST /automations/{id}/generate generates postsPerDay x lengthDays AI posts, each assigned a schedule slot. It is asynchronous: the response is 202 immediately (rate limited to 5 requests per 3600 seconds):

{
	"success": true,
	"data": {
		"id": "665f1b2a9c31a2b3c4d5e710",
		"kind": "automation",
		"status": "generating",
		"totalPosts": 14,
		"generatedCount": 0,
		"statusUrl": "/api/v1/automations/665f1b2a9c31a2b3c4d5e710"
	}
}

Poll GET /automations/{id} until the automation leaves generating: review means the batch is ready; back to draft means nothing was generated. Calling generate again while a run is in flight is a no-op that reports progress (generatedCount against totalPosts). Regenerating a automation in review replaces its posts.

curl -s -X POST "https://viraloop.io/api/v1/automations/<id>/generate" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"
curl -s "https://viraloop.io/api/v1/automations/<id>" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

viraloop automations generate <id> --json
viraloop automations get <id> --json

3. Review

GET /automations/{id}/posts lists the generated posts in schedule order. Each carries caption, postCaption, hashtags, its rationale and its assigned scheduledTime:

curl -s "https://viraloop.io/api/v1/automations/<id>/posts" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

viraloop automations posts <id> --json

To tweak the automation, PATCH /automations/{id} updates name, cadence, selectedAccounts, settings, ownerType, influencerId or tiktokMode. Editing is only allowed while the automation is in draft or review; any other status returns 409 with error type conflict. Sub-objects are replaced wholesale, so send the complete cadence, selectedAccounts or settings object, not just the changed keys.

curl -s -X PATCH "https://viraloop.io/api/v1/automations/<id>" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selectedAccounts": {"tiktok": ["665f1b2a9c31a2b3c4d5e700"]}}'

viraloop automations update <id> --accounts tiktok:<accountId> --json

If the content itself is off rather than the settings, regenerate instead: it replaces the batch.

4. Launch

POST /automations/{id}/launch converts every generated post into a scheduled post at its slot and activates the automation. It requires status review and at least one selected account:

{
	"success": true,
	"data": {
		"id": "665f1b2a9c31a2b3c4d5e710",
		"kind": "automation",
		"status": "active",
		"scheduled": 14,
		"failed": 0,
		"statusUrl": "/api/v1/automations/665f1b2a9c31a2b3c4d5e710"
	}
}

Posts render server-side after the call returns and publish automatically at their slots; nothing more is required. Track them with GET /posts?automationId=<id> or the calendar from posts and scheduling.

curl -s -X POST "https://viraloop.io/api/v1/automations/<id>/launch" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

viraloop automations launch <id> --json

Cancelling

POST /automations/{id}/cancel cancels the automation and removes its unsent posts. Content that already went out stays live. Cancelling is idempotent: a cancelled or completed automation returns cancelledPosts: 0.

curl -s -X POST "https://viraloop.io/api/v1/automations/<id>/cancel" \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

viraloop automations cancel <id> --json