# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/remote-access-and-apis/api-examples/create-workflow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.