---
title: Workflows API
description: Complete API reference for managing workflows, status transitions, and approval processes in TraceRTM
---

# Workflows API

Workflows define the lifecycle of items through status transitions, approvals, and automation rules. This API manages workflow definitions and item transitions.

## Endpoints Overview

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/projects/{project_id}/workflows` | List workflows |
| `POST` | `/v1/projects/{project_id}/workflows` | Create workflow |
| `GET` | `/v1/projects/{project_id}/workflows/{workflow_id}` | Get workflow |
| `PATCH` | `/v1/projects/{project_id}/workflows/{workflow_id}` | Update workflow |
| `DELETE` | `/v1/projects/{project_id}/workflows/{workflow_id}` | Delete workflow |
| `POST` | `/v1/projects/{project_id}/items/{item_id}/transitions` | Transition item |
| `GET` | `/v1/projects/{project_id}/items/{item_id}/transitions` | Get available transitions |
| `POST` | `/v1/projects/{project_id}/items/{item_id}/approve` | Approve item |
| `POST` | `/v1/projects/{project_id}/items/{item_id}/reject` | Reject item |

---

## The Workflow Object

```json
{
  "id": "wf_standard",
  "project_id": "proj_abc123",
  "name": "Standard Approval Workflow",
  "description": "Default workflow for requirements with review and approval",
  "item_types": ["requirement", "design"],
  "is_default": true,
  "statuses": [
    {
      "id": "draft",
      "name": "Draft",
      "color": "#6B7280",
      "category": "initial"
    },
    {
      "id": "in_review",
      "name": "In Review",
      "color": "#F59E0B",
      "category": "in_progress"
    },
    {
      "id": "approved",
      "name": "Approved",
      "color": "#10B981",
      "category": "final"
    },
    {
      "id": "rejected",
      "name": "Rejected",
      "color": "#EF4444",
      "category": "final"
    },
    {
      "id": "obsolete",
      "name": "Obsolete",
      "color": "#9CA3AF",
      "category": "archived"
    }
  ],
  "transitions": [
    {
      "id": "submit_for_review",
      "from": "draft",
      "to": "in_review",
      "name": "Submit for Review",
      "conditions": {
        "required_fields": ["title", "description"],
        "required_links": false
      }
    },
    {
      "id": "approve",
      "from": "in_review",
      "to": "approved",
      "name": "Approve",
      "requires_approval": true,
      "approval_roles": ["reviewer", "admin"]
    },
    {
      "id": "reject",
      "from": "in_review",
      "to": "rejected",
      "name": "Reject",
      "requires_comment": true
    },
    {
      "id": "revise",
      "from": ["rejected", "in_review"],
      "to": "draft",
      "name": "Return to Draft"
    },
    {
      "id": "obsolete",
      "from": ["approved", "rejected"],
      "to": "obsolete",
      "name": "Mark Obsolete"
    }
  ],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-06-01T14:00:00Z"
}
```

### Workflow Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique workflow identifier (prefix: `wf_`) |
| `project_id` | string | Parent project ID |
| `name` | string | Workflow name |
| `description` | string | Workflow description |
| `item_types` | array | Item types using this workflow |
| `is_default` | boolean | Default workflow for project |
| `statuses` | array | Available statuses |
| `transitions` | array | Allowed transitions |
| `created_at` | string | Creation timestamp |
| `updated_at` | string | Last update timestamp |

### Status Categories

| Category | Description |
|----------|-------------|
| `initial` | Starting status for new items |
| `in_progress` | Work in progress |
| `final` | Completed/approved status |
| `archived` | Obsolete or deprecated |

### Transition Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Transition identifier |
| `from` | string/array | Source status(es) |
| `to` | string | Target status |
| `name` | string | Display name |
| `requires_approval` | boolean | Needs approval action |
| `approval_roles` | array | Roles that can approve |
| `requires_comment` | boolean | Comment required |
| `conditions` | object | Transition conditions |

---

## List Workflows

Retrieve workflows for a project.

```http
GET /v1/projects/{project_id}/workflows
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `item_type` | string | — | Filter by item type |
| `include_system` | boolean | true | Include system workflows |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/workflows" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": [
    {
      "id": "wf_standard",
      "name": "Standard Approval Workflow",
      "item_types": ["requirement", "design"],
      "is_default": true,
      "status_count": 5,
      "transition_count": 5
    },
    {
      "id": "wf_test_execution",
      "name": "Test Execution Workflow",
      "item_types": ["test_case"],
      "is_default": false,
      "status_count": 4,
      "transition_count": 6
    }
  ]
}
```

### SDK Examples

#### Python

```python
from tracertm import TraceRTMClient

client = TraceRTMClient(api_key="rtm_live_sk_...")

# List all workflows
workflows = client.workflows.list(project_id="proj_abc123")

for wf in workflows.data:
    print(f"{wf.name}: {wf.status_count} statuses, {wf.transition_count} transitions")

# Get workflow for requirements
req_workflow = client.workflows.list(
    project_id="proj_abc123",
    item_type="requirement"
)
```

---

## Create Workflow

Create a new workflow.

```http
POST /v1/projects/{project_id}/workflows
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Workflow name |
| `description` | string | No | Description |
| `item_types` | array | Yes | Item types to use this |
| `is_default` | boolean | No | Set as default |
| `statuses` | array | Yes | Status definitions |
| `transitions` | array | Yes | Transition definitions |

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/workflows" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FDA Compliant Workflow",
    "description": "Workflow meeting FDA 21 CFR Part 11 requirements",
    "item_types": ["requirement"],
    "statuses": [
      {"id": "draft", "name": "Draft", "color": "#6B7280", "category": "initial"},
      {"id": "pending_review", "name": "Pending Review", "color": "#F59E0B", "category": "in_progress"},
      {"id": "under_review", "name": "Under Review", "color": "#3B82F6", "category": "in_progress"},
      {"id": "approved", "name": "Approved", "color": "#10B981", "category": "final"},
      {"id": "rejected", "name": "Rejected", "color": "#EF4444", "category": "final"}
    ],
    "transitions": [
      {
        "id": "submit",
        "from": "draft",
        "to": "pending_review",
        "name": "Submit for Review",
        "conditions": {"required_fields": ["title", "description", "rationale"]}
      },
      {
        "id": "start_review",
        "from": "pending_review",
        "to": "under_review",
        "name": "Start Review",
        "allowed_roles": ["reviewer", "admin"]
      },
      {
        "id": "approve",
        "from": "under_review",
        "to": "approved",
        "name": "Approve",
        "requires_approval": true,
        "approval_roles": ["reviewer", "admin"],
        "requires_comment": true
      },
      {
        "id": "reject",
        "from": "under_review",
        "to": "rejected",
        "name": "Reject",
        "requires_comment": true
      },
      {
        "id": "revise",
        "from": ["rejected", "pending_review", "under_review"],
        "to": "draft",
        "name": "Return to Draft"
      }
    ]
  }'
```

### SDK Examples

#### Python

```python
workflow = client.workflows.create(
    project_id="proj_abc123",
    name="FDA Compliant Workflow",
    item_types=["requirement"],
    statuses=[
        {"id": "draft", "name": "Draft", "color": "#6B7280", "category": "initial"},
        {"id": "approved", "name": "Approved", "color": "#10B981", "category": "final"}
    ],
    transitions=[
        {"id": "approve", "from": "draft", "to": "approved", "name": "Approve"}
    ]
)

print(f"Created workflow: {workflow.id}")
```

---

## Get Workflow

Retrieve a workflow by ID.

```http
GET /v1/projects/{project_id}/workflows/{workflow_id}
```

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/workflows/wf_standard" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

---

## Update Workflow

Update a workflow. Changing statuses may affect existing items.

```http
PATCH /v1/projects/{project_id}/workflows/{workflow_id}
```

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Workflow name |
| `description` | string | Description |
| `is_default` | boolean | Default status |
| `statuses` | array | Status definitions |
| `transitions` | array | Transition definitions |

### Request

```bash
curl -X PATCH "https://api.tracertm.dev/v1/projects/proj_abc123/workflows/wf_standard" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "transitions": [
      {
        "id": "approve",
        "from": "in_review",
        "to": "approved",
        "name": "Approve",
        "requires_approval": true,
        "approval_roles": ["reviewer", "admin", "manager"]
      }
    ]
  }'
```

---

## Delete Workflow

Delete a workflow. Items using this workflow will need reassignment.

```http
DELETE /v1/projects/{project_id}/workflows/{workflow_id}
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `migrate_to` | string | Yes | Workflow ID to migrate items to |

### Request

```bash
curl -X DELETE "https://api.tracertm.dev/v1/projects/proj_abc123/workflows/wf_old?migrate_to=wf_standard" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

---

## Transition Item

Change an item's status according to workflow rules.

```http
POST /v1/projects/{project_id}/items/{item_id}/transitions
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `transition_id` | string | Yes | Transition to execute |
| `comment` | string | Conditional | Comment (if required) |

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/items/item_req_001/transitions" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "transition_id": "submit_for_review",
    "comment": "Ready for technical review"
  }'
```

### Response

```json
{
  "data": {
    "item_id": "item_req_001",
    "previous_status": "draft",
    "new_status": "in_review",
    "transition_id": "submit_for_review",
    "transitioned_by": "user_engineer123",
    "transitioned_at": "2024-12-08T10:00:00Z",
    "comment": "Ready for technical review"
  }
}
```

### SDK Examples

#### Python

```python
result = client.items.transition(
    project_id="proj_abc123",
    item_id="item_req_001",
    transition_id="submit_for_review",
    comment="Ready for technical review"
)

print(f"Status changed: {result.previous_status} → {result.new_status}")
```

#### TypeScript

```typescript
const result = await client.items.transition({
  projectId: 'proj_abc123',
  itemId: 'item_req_001',
  transitionId: 'submit_for_review',
  comment: 'Ready for technical review'
});

console.log(`Status: ${result.previousStatus} → ${result.newStatus}`);
```

---

## Get Available Transitions

Get transitions available for an item's current status.

```http
GET /v1/projects/{project_id}/items/{item_id}/transitions
```

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items/item_req_001/transitions" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": {
    "item_id": "item_req_001",
    "current_status": "in_review",
    "available_transitions": [
      {
        "id": "approve",
        "name": "Approve",
        "to_status": "approved",
        "requires_approval": true,
        "can_execute": true,
        "conditions_met": true
      },
      {
        "id": "reject",
        "name": "Reject",
        "to_status": "rejected",
        "requires_comment": true,
        "can_execute": true,
        "conditions_met": true
      },
      {
        "id": "revise",
        "name": "Return to Draft",
        "to_status": "draft",
        "can_execute": true,
        "conditions_met": true
      }
    ]
  }
}
```

### SDK Examples

#### Python

```python
transitions = client.items.available_transitions(
    project_id="proj_abc123",
    item_id="item_req_001"
)

print(f"Current status: {transitions.current_status}")
for t in transitions.available_transitions:
    print(f"  - {t.name} → {t.to_status}")
```

---

## Approve Item

Approve an item (shortcut for approval transitions).

```http
POST /v1/projects/{project_id}/items/{item_id}/approve
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `comment` | string | No | Approval comment |
| `level` | integer | No | Approval level (for multi-level) |

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/items/item_req_001/approve" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Reviewed and approved. Implementation can proceed."
  }'
```

### Response

```json
{
  "data": {
    "item_id": "item_req_001",
    "previous_status": "in_review",
    "new_status": "approved",
    "approved_by": "user_reviewer123",
    "approved_at": "2024-12-08T10:00:00Z",
    "approval_level": 1,
    "total_levels": 1,
    "comment": "Reviewed and approved. Implementation can proceed."
  }
}
```

### SDK Examples

#### Python

```python
result = client.items.approve(
    project_id="proj_abc123",
    item_id="item_req_001",
    comment="Reviewed and approved"
)

print(f"Approved by: {result.approved_by}")
```

---

## Reject Item

Reject an item (shortcut for rejection transitions).

```http
POST /v1/projects/{project_id}/items/{item_id}/reject
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `comment` | string | Yes | Rejection reason |
| `to_status` | string | No | Target status (default: rejected) |

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/items/item_req_001/reject" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Requirement is too vague. Please add specific acceptance criteria.",
    "to_status": "draft"
  }'
```

### Response

```json
{
  "data": {
    "item_id": "item_req_001",
    "previous_status": "in_review",
    "new_status": "draft",
    "rejected_by": "user_reviewer123",
    "rejected_at": "2024-12-08T10:00:00Z",
    "comment": "Requirement is too vague. Please add specific acceptance criteria."
  }
}
```

---

## Error Responses

### Invalid Transition

```json
{
  "error": {
    "code": "WORKFLOW_TRANSITION_INVALID",
    "message": "Cannot transition from 'draft' to 'approved'",
    "status": 422,
    "details": {
      "current_status": "draft",
      "requested_transition": "approve",
      "available_transitions": ["submit_for_review"]
    }
  }
}
```

### Conditions Not Met

```json
{
  "error": {
    "code": "WORKFLOW_CONDITIONS_NOT_MET",
    "message": "Transition conditions not met",
    "status": 422,
    "details": {
      "missing_fields": ["description", "rationale"],
      "missing_links": true
    }
  }
}
```

### Approval Not Allowed

```json
{
  "error": {
    "code": "APPROVAL_NOT_ALLOWED",
    "message": "You don't have permission to approve this item",
    "status": 403,
    "details": {
      "required_roles": ["reviewer", "admin"],
      "user_role": "editor"
    }
  }
}
```

---

## Related Documentation

- [Requirements API](/docs/api-reference/rest-api/endpoints/requirements) - Item management
- [Projects API](/docs/api-reference/rest-api/endpoints/projects) - Project settings
- [Users API](/docs/api-reference/rest-api/endpoints/users) - Role management
