# Create Workflow

### Endpoint

`POST /api/workflows/create`

### Authentication

This endpoint requires API key authentication.

### Headers

| Header          | Value                   | Description                         |
| --------------- | ----------------------- | ----------------------------------- |
| `Authorization` | `Bearer <YOUR_API_KEY>` | Your groundcover API key            |
| `Content-Type`  | `text/plain`            | The request body should be raw YAML |

### Request Body

The request body should contain raw YAML defining the workflow configuration. The YAML structure should include:

* `id`: Unique identifier for the workflow
* `description`: Human-readable description
* `triggers`: Array of trigger conditions
* `actions`: Array of actions to perform when triggered
* `name`: Display name for the workflow
* `consts` (optional): Constants and helper variables

### Example Request

```bash
curl -L \
  --request POST \
  --url 'https://api.groundcover.com/api/workflows/create' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: text/plain' \
  --data 'id: example-workflow
description: Example workflow for API documentation
triggers:
- type: alert
  filters:
  - key: annotations.example-workflow
    value: enabled
name: example-workflow
consts:
  severity: keep.dictget({{ alert.annotations }}, "_gc_severity", "info")
  title: keep.dictget({{ alert.annotations }}, "_gc_issue_header", "{{ alert.alertname }}")
actions:
- name: webhook-action
  provider:
    type: webhook
    config: "{{ providers.webhook-provider }}"
    with:
      body:
        alert_name: "{{ consts.title }}"
        severity: "{{ consts.severity }}"'
```

### Response

```json
{
  "workflow_id": "xxxxx-xxxx-xxxxx-xxxx-xxxxx",
  "status": "created",
  "revision": 1
}
```

### Workflow YAML Structure

#### Basic Structure

```yaml
id: workflow-id
description: Workflow description
triggers:
  - type: alert
    filters:
      - key: filter-key
        value: filter-value
name: workflow-name
consts:
  variable_name: value
actions:
  - name: action-name
    provider:
      type: provider-type
      config: provider-config
      with:
        action-specific-parameters
```

### Choosing Integration Providers

To route alerts to a specific integration (Slack, PagerDuty, webhook, etc.), use the `config` field in the provider section to reference your configured integration by name.

#### Example: Slack Integration

```yaml
actions:
- if: '{{ alert.status }} == "firing"'
  name: slack-action-firing
  provider:
    config: '{{ providers.integration-name }}'
    type: slack
    with:
      attachments:
      - color: '#FF0000'
        footer: 'groundcover.com'
        footer_icon: 'https://app.groundcover.com/favicon.ico'
        text: 'Alert details here'
        title: 'Firing: {{ alert.alertname }}'
        ts: keep.utcnowtimestamp()
        type: plain_text
      message: ' '
```

#### Provider Configuration

* `config: '{{ providers.integration-name }}'` - References a specific integration you've configured in groundcover
* `type` - Specifies the integration type (slack, webhook, pagerduty, opsgenie)
* Replace `integration-name` with your actual integration name.

The integration name must match the name of an integration you've previously configured in your groundcover workspace.

### References

For workflow examples and advanced configurations, see the [groundcover workflow examples documentation](https://docs.groundcover.com/use-groundcover/workflows/workflow-examples).