> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>

**Example**

```bash theme={null}
curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/automations \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "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"
    }
  ]
}
```

<ResponseField name="automations[].id" type="string">Automation UUID.</ResponseField>
<ResponseField name="automations[].organization_id" type="string">Organization UUID.</ResponseField>
<ResponseField name="automations[].space_id" type="string">Space UUID.</ResponseField>
<ResponseField name="automations[].name" type="string">Display name.</ResponseField>
<ResponseField name="automations[].kind" type="string">Automation kind: `social_post`, `reverse_tunnel`, `scheduled`, or `webhook`.</ResponseField>
<ResponseField name="automations[].config" type="object">Kind-specific configuration JSON.</ResponseField>
<ResponseField name="automations[].status" type="string">Current status: `draft`, `pending_approval`, `active`, `paused`, or `rejected`.</ResponseField>
<ResponseField name="automations[].created_by_user_id" type="string">UUID of the human user who created this automation, or `null`.</ResponseField>
<ResponseField name="automations[].created_by_service_account_id" type="string">UUID of the service account that created this automation, or `null`.</ResponseField>
<ResponseField name="automations[].last_run_at" type="string">Timestamp of the most recent execution, or `null`.</ResponseField>
<ResponseField name="automations[].last_error" type="string">Error message from the most recent failed run, or `null`.</ResponseField>

***

## Create an automation

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

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

**Path parameters**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>

**Request body**

<ParamField body="name" type="string" required>
  Display name. Whitespace is stripped.
</ParamField>

<ParamField body="kind" type="string" required>
  Automation kind. One of: `social_post`, `reverse_tunnel`, `scheduled`, `webhook`.
</ParamField>

<ParamField body="config" type="object">
  Kind-specific configuration. Defaults to `{}` if omitted.
</ParamField>

<ParamField body="status" type="string">
  Initial status. One of: `draft`, `pending_approval`, `active`, `paused`. Defaults to `draft`. Ignored for service account callers (always set to `pending_approval`).
</ParamField>

<ParamField body="description" type="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.
</ParamField>

<ParamField body="oauth_token" type="string">
  Plain-text OAuth token to store encrypted. Not available to service accounts.
</ParamField>

**Example**

```bash theme={null}
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`

```json theme={null}
{
  "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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="automationId" type="string" required>Automation UUID.</ParamField>

**Request body**

<ParamField body="name" type="string">
  New display name.
</ParamField>

<ParamField body="config" type="object">
  Replacement configuration JSON.
</ParamField>

<ParamField body="status" type="string">
  New status: `draft`, `pending_approval`, `active`, or `paused`.
</ParamField>

<ParamField body="oauth_token" type="string">
  New OAuth token (replaces the existing encrypted value). Not available to service accounts.
</ParamField>

**Example** — pause an automation

```bash theme={null}
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`

```json theme={null}
{
  "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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="automationId" type="string" required>Automation UUID.</ParamField>

**Example**

```bash theme={null}
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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.