Automations

Create and manage space automations that trigger actions on a schedule, webhook, or social post event.

Automations are workflow definitions scoped to a space. Each automation has a kind that determines how it is triggered, and a config object that varies by kind.

Valid kinds: social_post, reverse_tunnel, scheduled, webhook.

Valid statuses: draft, pending_approval, active, paused, rejected.

When an automation is created by a service account (AI staff), its status is always set to pending_approval regardless of the value in the request body. A human with the appropriate permissions must approve it before it becomes active.

List automations

GET /api/v1/organizations/{orgId}/spaces/{spaceId}/automations

Returns all automations for a space. Requires the files.read permission and access to the space.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

Example

curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/automations \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "automations": [
    {
      "id": "018e1234-abcd-7000-8000-0000000000a0",
      "organization_id": "018e1234-abcd-7000-8000-000000000000",
      "space_id": "018e1234-abcd-7000-8000-000000000002",
      "name": "Weekly digest",
      "kind": "scheduled",
      "config": { "cron": "0 9 * * MON", "channel": "general" },
      "status": "active",
      "created_by_user_id": "018e1234-abcd-7000-8000-000000000050",
      "created_by_service_account_id": null,
      "reviewed_by_user_id": null,
      "reviewed_at": null,
      "rejection_reason": null,
      "last_run_at": "2024-03-18T09:00:00Z",
      "last_error": null,
      "created_at": "2024-03-01T10:00:00Z",
      "updated_at": "2024-03-18T09:00:05Z"
    }
  ]
}

automations[].id · string

Automation UUID.

automations[].organization_id · string

Organization UUID.

automations[].space_id · string

Space UUID.

automations[].name · string

Display name.

automations[].kind · string

Automation kind: social_post, reverse_tunnel, scheduled, or webhook.

automations[].config · object

Kind-specific configuration JSON.

automations[].status · string

Current status: draft, pending_approval, active, paused, or rejected.

automations[].created_by_user_id · string

UUID of the human user who created this automation, or null.

automations[].created_by_service_account_id · string

UUID of the service account that created this automation, or null.

automations[].last_run_at · string

Timestamp of the most recent execution, or null.

automations[].last_error · string

Error message from the most recent failed run, or null.

---

Create an automation

POST /api/v1/organizations/{orgId}/spaces/{spaceId}/automations

Requires the files.write permission and access to the space.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

Request body

name · string · required

Display name. Whitespace is stripped.

kind · string · required

Automation kind. One of: social_post, reverse_tunnel, scheduled, webhook.

config · object

Kind-specific configuration. Defaults to {} if omitted.

status · string

Initial status. One of: draft, pending_approval, active, paused. Defaults to draft. Ignored for service account callers (always set to pending_approval).

description · string

Optional human-readable description of the automation’s intent. For service account-created automations, this is merged into config as proposal_note for reviewers.

oauth_token · string

Plain-text OAuth token to store encrypted. Not available to service accounts.

Example

curl -X POST \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/automations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly digest",
    "kind": "scheduled",
    "config": {"cron": "0 9 * * MON", "channel": "general"},
    "status": "active"
  }'

Response 201 Created

{
  "automation": {
    "id": "018e1234-abcd-7000-8000-0000000000a1",
    "organization_id": "018e1234-abcd-7000-8000-000000000000",
    "space_id": "018e1234-abcd-7000-8000-000000000002",
    "name": "Weekly digest",
    "kind": "scheduled",
    "config": {"cron": "0 9 * * MON", "channel": "general"},
    "status": "active",
    "created_by_user_id": "018e1234-abcd-7000-8000-000000000050",
    "created_at": "2024-03-20T10:00:00Z",
    "updated_at": "2024-03-20T10:00:00Z"
  }
}

---

Update an automation

PATCH /api/v1/organizations/{orgId}/spaces/{spaceId}/automations/{automationId}

Partially updates an automation. Requires the files.write permission. All fields are optional.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

automationId · string · required

Automation UUID.

Request body

name · string

New display name.

config · object

Replacement configuration JSON.

status · string

New status: draft, pending_approval, active, or paused.

oauth_token · string

New OAuth token (replaces the existing encrypted value). Not available to service accounts.

Example — pause an automation

curl -X PATCH \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/automations/YOUR_AUTOMATION_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

Response 200 OK

{
  "automation": { ... }
}

Returns the full updated automation object.

---

Delete an automation

DELETE /api/v1/organizations/{orgId}/spaces/{spaceId}/automations/{automationId}

Permanently deletes an automation. Requires the files.write permission.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

automationId · string · required

Automation UUID.

Example

curl -X DELETE \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/automations/YOUR_AUTOMATION_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204 No Content