# Start the published workflow version

```
POST /api/v1/workflows/{workflow_id}/runs
```

<CodeGroup>
```bash cURL
curl --request POST \
  --url '/api/v1/workflows/{workflow_id}/runs' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": {
    "order_id": 1842,
    "customer_email": "customer@example.com"
  }
}'
```

```javascript JavaScript
const response = await fetch('/api/v1/workflows/{workflow_id}/runs', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "payload": {
      "order_id": 1842,
      "customer_email": "customer@example.com"
    }
  })
});

const data = await response.json();
```

```python Python
import requests

response = requests.request(
    "POST",
    "/api/v1/workflows/{workflow_id}/runs",
    headers={
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    json={
      "payload": {
        "order_id": 1842,
        "customer_email": "customer@example.com"
      }
    },
)

print(response.json())
```

```php PHP
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', '/api/v1/workflows/{workflow_id}/runs', [
    'headers' => [
        'Authorization' => 'Bearer <token>',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'payload' => [
            'order_id' => 1842,
            'customer_email' => 'customer@example.com',
        ],
    ],
]);

echo $response->getBody();
```

```go Go
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "payload": {
    "order_id": 1842,
    "customer_email": "customer@example.com"
  }
}`)
	req, _ := http.NewRequest("POST", "/api/v1/workflows/{workflow_id}/runs", body)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
```

```ruby Ruby
require "net/http"

uri = URI("/api/v1/workflows/{workflow_id}/runs")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "payload": {
      "order_id": 1842,
      "customer_email": "customer@example.com"
    }
  }
JSON

response = http.request(request)
puts response.body
```

```java Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("/api/v1/workflows/{workflow_id}/runs"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
        {
          "payload": {
            "order_id": 1842,
            "customer_email": "customer@example.com"
          }
        }
        """))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
```
</CodeGroup>

## Authorization

A bearer token in the `Authorization` header.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workflow_id` | string | Yes |  |

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | No | Optional unique key for this logical attempt. Supplying the same key and request returns the original run for 24 hours. When omitted, the request starts normally without protection against duplicate runs caused by caller retries. |
| `X-Request-Id` | string | No |  |

## Request body

`application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No |  |

## Responses

<AccordionGroup>
<Accordion title="202 · The run was accepted. On a replay the Idempotent-Replayed response header is true.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | RunReference | Yes |  |
| `data.id` | string | Yes |  |
| `data.object` | string | Yes |  |
| `data.workflow_id` | string or null | Yes |  |
| `data.status` | string | Yes | One of: `pending`, `running`, `waiting`, `finished`, `failed`, `canceled` |
| `data.started_at` | string (date-time) or null (date-time) | No |  |
| `data.finished_at` | string (date-time) or null (date-time) | No |  |
| `data.created_at` | string (date-time) or null (date-time) | Yes |  |
| `data.updated_at` | string (date-time) or null (date-time) | Yes |  |
| `request_id` | string | Yes |  |

```json
{
  "data": {
    "id": "string",
    "object": "run",
    "workflow_id": "string",
    "status": "pending",
    "started_at": "2024-01-01T00:00:00Z",
    "finished_at": "2024-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "request_id": "string"
}
```
</Accordion>
<Accordion title="401 · The Bearer token is missing, malformed, expired, or revoked.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | Yes |  |
| `error.code` | string | Yes |  |
| `error.message` | string | Yes |  |
| `error.details` | object | No |  |
| `request_id` | string | Yes |  |

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
```
</Accordion>
<Accordion title="403 · The token lacks the required ability.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | Yes |  |
| `error.code` | string | Yes |  |
| `error.message` | string | Yes |  |
| `error.details` | object | No |  |
| `request_id` | string | Yes |  |

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
```
</Accordion>
<Accordion title="404 · The resource was not found in the token workspace.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | Yes |  |
| `error.code` | string | Yes |  |
| `error.message` | string | Yes |  |
| `error.details` | object | No |  |
| `request_id` | string | Yes |  |

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
```
</Accordion>
<Accordion title="409 · The operation conflicts with current state or idempotency history.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | Yes |  |
| `error.code` | string | Yes |  |
| `error.message` | string | Yes |  |
| `error.details` | object | No |  |
| `request_id` | string | Yes |  |

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
```
</Accordion>
<Accordion title="422 · The request is invalid or the workspace cannot perform the operation.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | Yes |  |
| `error.code` | string | Yes |  |
| `error.message` | string | Yes |  |
| `error.details` | object | No |  |
| `request_id` | string | Yes |  |

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
```
</Accordion>
<Accordion title="429 · A per-token rate limit was exceeded.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | Yes |  |
| `error.code` | string | Yes |  |
| `error.message` | string | Yes |  |
| `error.details` | object | No |  |
| `request_id` | string | Yes |  |

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
```
</Accordion>
<Accordion title="503 · The site administrator has disabled the Workspace API.">
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | Yes |  |
| `error.code` | string | Yes |  |
| `error.message` | string | Yes |  |
| `error.details` | object | No |  |
| `request_id` | string | Yes |  |

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "request_id": "string"
}
```
</Accordion>
</AccordionGroup>