# Workflows

Source: https://opvs.ai/docs/api/workflows

## `GET` /api/v1/workflows/definitions

**List Definitions**

**Parameters**

- `code` (query, any, optional) — Filter by definition code
- `status` (query, any, optional) — Filter by lifecycle status
- `skip` (query, integer, optional)
- `limit` (query, integer, optional)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/workflows/definitions' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/workflows/definitions",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/definitions", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/workflows/definitions", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/workflows/definitions

**Create Definition**

Register a validated SMEAC workflow definition.

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/workflows/definitions' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "definition": {
    "code": "string",
    "version": "string",
    "situation": {},
    "mission": {
      "intent": "string",
      "done_when": [
        "string"
      ]
    },
    "inputs_schema": {},
    "execution": [
      {
        "id": "string",
        "intent": {},
        "instruction": {},
        "consumes": [
          {}
        ],
        "produces": {},
        "requires": [
          {}
        ],
        "retry": {},
        "timeout": {},
        "on_fail": {},
        "type": "act",
        "uses": [
          {}
        ]
      }
    ],
    "roe": [
      "string"
    ],
    "command": {}
  },
  "status": "draft"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/workflows/definitions",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"definition": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "status": "draft"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/definitions", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"definition": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "status": "draft"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"definition": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "status": "draft"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/workflows/definitions", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/workflows/definitions/id/{definition_id}

**Get Definition By Id**

**Parameters**

- `definition_id` (path, string, required)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/workflows/definitions/id/{definition_id}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/workflows/definitions/id/{definition_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/definitions/id/{definition_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/workflows/definitions/id/{definition_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/workflows/definitions/{code}/{version}

**Get Definition**

Fetch one pinned definition by (code, version).

**Parameters**

- `code` (path, string, required)
- `version` (path, string, required)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `PATCH` /api/v1/workflows/definitions/{definition_id}/status

**Update Definition Status**

Transition a definition's lifecycle status (draft → published → deprecated).

**Parameters**

- `definition_id` (path, string, required)
- `status` (query, string, required)

```bash
curl -X PATCH 'https://app.opvs.ai/api/v1/workflows/definitions/{definition_id}/status' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.patch(
    "https://app.opvs.ai/api/v1/workflows/definitions/{definition_id}/status",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/definitions/{definition_id}/status", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("PATCH", "https://app.opvs.ai/api/v1/workflows/definitions/{definition_id}/status", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/workflows/definitions/{code}/{version}/bind

**Bind Definition**

Classify a proposed customisation of a base definition as `args` vs `fork`.

**Parameters**

- `code` (path, string, required)
- `version` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/bind' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "proposed": {
    "code": "string",
    "version": "string",
    "situation": {},
    "mission": {
      "intent": "string",
      "done_when": [
        "string"
      ]
    },
    "inputs_schema": {},
    "execution": [
      {
        "id": "string",
        "intent": {},
        "instruction": {},
        "consumes": [
          {}
        ],
        "produces": {},
        "requires": [
          {}
        ],
        "retry": {},
        "timeout": {},
        "on_fail": {},
        "type": "act",
        "uses": [
          {}
        ]
      }
    ],
    "roe": [
      "string"
    ],
    "command": {}
  },
  "engagement_id": "string"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/bind",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"proposed": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "engagement_id": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/bind", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"proposed": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "engagement_id": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"proposed": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "engagement_id": "string"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/bind", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/workflows/definitions/{code}/{version}/fork

**Fork Definition**

Fork a base definition into a client-scoped STRUCTURAL variant (D7-guarded).

**Parameters**

- `code` (path, string, required)
- `version` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/fork' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "proposed": {
    "code": "string",
    "version": "string",
    "situation": {},
    "mission": {
      "intent": "string",
      "done_when": [
        "string"
      ]
    },
    "inputs_schema": {},
    "execution": [
      {
        "id": "string",
        "intent": {},
        "instruction": {},
        "consumes": [
          {}
        ],
        "produces": {},
        "requires": [
          {}
        ],
        "retry": {},
        "timeout": {},
        "on_fail": {},
        "type": "act",
        "uses": [
          {}
        ]
      }
    ],
    "roe": [
      "string"
    ],
    "command": {}
  },
  "engagement_id": "string",
  "status": "draft"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/fork",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"proposed": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "engagement_id": "string", "status": "draft"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/fork", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"proposed": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "engagement_id": "string", "status": "draft"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"proposed": {"code": "string", "version": "string", "situation": {}, "mission": {"intent": "string", "done_when": ["string"]}, "inputs_schema": {}, "execution": [{"id": "string", "intent": {}, "instruction": {}, "consumes": [{}], "produces": {}, "requires": [{}], "retry": {}, "timeout": {}, "on_fail": {}, "type": "act", "uses": [{}]}], "roe": ["string"], "command": {}}, "engagement_id": "string", "status": "draft"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/fork", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/workflows/runs

**Compile Run**

Compile a pinned definition into a durable run + a board task DAG.

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/workflows/runs' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "definition_code": "string",
  "definition_version": "string",
  "engagement_id": "string",
  "board_id": "string",
  "tenant_id": "string",
  "args": {},
  "office_ctx": {
    "office_id": "string",
    "requester_role_id": "string"
  }
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/workflows/runs",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"definition_code": "string", "definition_version": "string", "engagement_id": "string", "board_id": "string", "tenant_id": "string", "args": {}, "office_ctx": {"office_id": "string", "requester_role_id": "string"}},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/runs", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"definition_code": "string", "definition_version": "string", "engagement_id": "string", "board_id": "string", "tenant_id": "string", "args": {}, "office_ctx": {"office_id": "string", "requester_role_id": "string"}})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"definition_code": "string", "definition_version": "string", "engagement_id": "string", "board_id": "string", "tenant_id": "string", "args": {}, "office_ctx": {"office_id": "string", "requester_role_id": "string"}}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/workflows/runs", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/workflows/runs/{run_id}/advance

**Advance Run**

Advance a run by one heartbeat pulse (task 2.3 — the advancement loop).

**Parameters**

- `run_id` (path, string, required)

```bash
curl -X POST 'https://app.opvs.ai/api/v1/workflows/runs/{run_id}/advance' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/workflows/runs/{run_id}/advance",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/runs/{run_id}/advance", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/workflows/runs/{run_id}/advance", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/workflows/runs/{run_id}

**Get Run**

Fetch a compiled run + its steps (the DAG the loop and a human both read).

**Parameters**

- `run_id` (path, string, required)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/workflows/runs/{run_id}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/workflows/runs/{run_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/workflows/runs/{run_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/workflows/runs/{run_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## List Definitions

`GET https://app.opvs.ai/api/v1/workflows/definitions`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Create Definition

`POST https://app.opvs.ai/api/v1/workflows/definitions`

Register a validated SMEAC workflow definition.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get Definition By Id

`GET https://app.opvs.ai/api/v1/workflows/definitions/id/{definition_id}`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get Definition

`GET https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}`

Fetch one pinned definition by (code, version).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Update Definition Status

`PATCH https://app.opvs.ai/api/v1/workflows/definitions/{definition_id}/status`

Transition a definition's lifecycle status (draft → published → deprecated).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Bind Definition

`POST https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/bind`

Classify a proposed customisation of a base definition as `args` vs `fork`.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Fork Definition

`POST https://app.opvs.ai/api/v1/workflows/definitions/{code}/{version}/fork`

Fork a base definition into a client-scoped STRUCTURAL variant (D7-guarded).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Compile Run

`POST https://app.opvs.ai/api/v1/workflows/runs`

Compile a pinned definition into a durable run + a board task DAG.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Advance Run

`POST https://app.opvs.ai/api/v1/workflows/runs/{run_id}/advance`

Advance a run by one heartbeat pulse (task 2.3 — the advancement loop).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get Run

`GET https://app.opvs.ai/api/v1/workflows/runs/{run_id}`

Fetch a compiled run + its steps (the DAG the loop and a human both read).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |