---
title: "Items API"
description: "REST API endpoints for managing traceable items - requirements, test cases, bugs, and more"
---

# Items API

Items are the core traceable artifacts in TraceRTM. They represent requirements, test cases, bugs, user stories, and any other work items that need traceability.

## Endpoints Overview

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/projects/{project_id}/items` | List items in project |
| `POST` | `/v1/projects/{project_id}/items` | Create item in project |
| `GET` | `/v1/items/{id}` | Get item details |
| `PATCH` | `/v1/items/{id}` | Update item |
| `DELETE` | `/v1/items/{id}` | Delete item |
| `GET` | `/v1/items/{id}/history` | Get item version history |
| `GET` | `/v1/items/{id}/links` | Get item's traceability links |
| `POST` | `/v1/items/{id}/transition` | Transition item status |

## Item Object

```json
{
  "id": "item_abc123xyz",
  "project_id": "proj_456",
  "type": "requirement",
  "title": "User Authentication",
  "description": "The system shall support OAuth 2.0 authentication for secure user login.",
  "status": "approved",
  "priority": "high",
  "custom_id": "REQ-001",
  "custom_fields": {
    "platform": ["web", "mobile"],
    "component": "auth",
    "story_points": 8
  },
  "tags": ["security", "mvp", "sprint-1"],
  "assignee_id": "user_xyz789",
  "reporter_id": "user_abc123",
  "parent_id": null,
  "children_ids": ["item_child1", "item_child2"],
  "version": 5,
  "locked": false,
  "locked_by": null,
  "links_count": {
    "total": 8,
    "inbound": 3,
    "outbound": 5
  },
  "comments_count": 12,
  "attachments_count": 2,
  "created_at": "2025-01-10T09:00:00Z",
  "updated_at": "2025-01-15T14:30:00Z",
  "created_by": "user_abc123",
  "updated_by": "user_xyz789"
}
```

## Item Types

| Type | Description | Common Fields |
|------|-------------|---------------|
| `requirement` | Functional or non-functional requirement | priority, status, acceptance_criteria |
| `test_case` | Test case or test specification | steps, expected_result, test_type |
| `bug` | Bug or defect report | severity, reproduction_steps |
| `user_story` | Agile user story | acceptance_criteria, story_points |
| `task` | Development or work task | estimate, assignee |
| `risk` | Risk assessment item | probability, impact |
| `decision` | Design or architectural decision | rationale, alternatives |
| `custom` | Custom item type | Configurable |

## List Items

Retrieve items from a project with filtering and pagination.

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

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | string | Filter by item type |
| `status` | string | Filter by status |
| `priority` | string | Filter by priority |
| `assignee_id` | string | Filter by assignee |
| `tag` | string | Filter by tag (multiple allowed) |
| `search` | string | Full-text search |
| `parent_id` | string | Filter by parent item |
| `has_links` | boolean | Filter items with/without links |
| `created_after` | datetime | Filter by creation date |
| `updated_after` | datetime | Filter by update date |
| `sort` | string | Sort field: `created_at`, `updated_at`, `priority`, `title` |
| `page` | integer | Page number |
| `per_page` | integer | Items per page (max 100) |

### Request

```bash
curl -X GET "https://api.tracertm.dev/v1/projects/proj_456/items?type=requirement&status=approved&sort=-priority" \
  -H "Authorization: Bearer $TRACERTM_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "item_abc123",
      "type": "requirement",
      "title": "User Authentication",
      "status": "approved",
      "priority": "high",
      "custom_id": "REQ-001",
      "links_count": {"total": 8},
      "updated_at": "2025-01-15T14:30:00Z"
    },
    {
      "id": "item_def456",
      "type": "requirement",
      "title": "Password Reset",
      "status": "approved",
      "priority": "medium",
      "custom_id": "REQ-002",
      "links_count": {"total": 5},
      "updated_at": "2025-01-14T10:00:00Z"
    }
  ],
  "meta": {
    "total": 80,
    "page": 1,
    "per_page": 20
  }
}
```

### Python Example

```python
from tracertm import TraceRTMClient

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

# List all requirements
items = await client.items.list(
    project_id="proj_456",
    type="requirement",
    status="approved",
    sort="-priority"
)

# Search items
search_results = await client.items.list(
    project_id="proj_456",
    search="authentication"
)

# Filter by multiple tags
tagged_items = await client.items.list(
    project_id="proj_456",
    tags=["security", "mvp"]
)

# Iterate through all items
async for item in client.items.list_all(project_id="proj_456"):
    print(f"{item.custom_id}: {item.title}")
```

## Create Item

Create a new item in a project.

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

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | Item type |
| `title` | string | Yes | Item title (3-500 chars) |
| `description` | string | No | Detailed description (Markdown) |
| `status` | string | No | Initial status (default: `draft`) |
| `priority` | string | No | Priority level |
| `custom_id` | string | No | Custom identifier |
| `custom_fields` | object | No | Custom field values |
| `tags` | array | No | Tags/labels |
| `assignee_id` | string | No | Assigned user ID |
| `parent_id` | string | No | Parent item ID (for hierarchy) |
| `attachments` | array | No | File attachment IDs |

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_456/items" \
  -H "Authorization: Bearer $TRACERTM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "requirement",
    "title": "Multi-Factor Authentication",
    "description": "## Overview\nThe system shall support MFA using TOTP.\n\n## Acceptance Criteria\n- Support Google Authenticator\n- Support hardware keys",
    "priority": "high",
    "status": "draft",
    "custom_fields": {
      "platform": ["web", "mobile"],
      "component": "auth",
      "story_points": 13
    },
    "tags": ["security", "sprint-2"],
    "assignee_id": "user_xyz789"
  }'
```

### Response

```json
{
  "data": {
    "id": "item_new789",
    "project_id": "proj_456",
    "type": "requirement",
    "title": "Multi-Factor Authentication",
    "description": "## Overview\nThe system shall support MFA using TOTP...",
    "status": "draft",
    "priority": "high",
    "custom_id": "REQ-003",
    "custom_fields": {
      "platform": ["web", "mobile"],
      "component": "auth",
      "story_points": 13
    },
    "tags": ["security", "sprint-2"],
    "assignee_id": "user_xyz789",
    "version": 1,
    "created_at": "2025-01-15T16:00:00Z",
    "created_by": "user_abc123"
  }
}
```

### Python Example

```python
# Create a requirement
item = await client.items.create(
    project_id="proj_456",
    type="requirement",
    title="Multi-Factor Authentication",
    description="The system shall support MFA using TOTP.",
    priority="high",
    custom_fields={
        "platform": ["web", "mobile"],
        "story_points": 13
    },
    tags=["security", "sprint-2"]
)

# Create a test case linked to requirement
test_case = await client.items.create(
    project_id="proj_456",
    type="test_case",
    title="Test MFA TOTP Verification",
    description="Verify TOTP codes are validated correctly",
    custom_fields={
        "test_type": "integration",
        "steps": [
            "Generate TOTP code",
            "Submit code to verification endpoint",
            "Verify successful authentication"
        ],
        "expected_result": "User is authenticated"
    }
)

# Create with parent (hierarchical items)
child_item = await client.items.create(
    project_id="proj_456",
    type="requirement",
    title="TOTP Generation",
    parent_id=item.id
)
```

## Get Item

Retrieve a specific item by ID.

```http
GET /v1/items/{id}
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `include` | string | Include related data: `links`, `comments`, `history`, `children` |
| `version` | integer | Get specific version (default: latest) |

### Request

```bash
curl -X GET "https://api.tracertm.dev/v1/items/item_abc123?include=links,comments" \
  -H "Authorization: Bearer $TRACERTM_API_KEY"
```

### Response

```json
{
  "data": {
    "id": "item_abc123",
    "project_id": "proj_456",
    "type": "requirement",
    "title": "User Authentication",
    "description": "The system shall support OAuth 2.0 authentication.",
    "status": "approved",
    "priority": "high",
    "custom_id": "REQ-001",
    "version": 5,
    "links": [
      {
        "id": "link_123",
        "type": "verified_by",
        "target": {
          "id": "item_test1",
          "type": "test_case",
          "title": "Test OAuth Login"
        }
      }
    ],
    "comments": [
      {
        "id": "comment_1",
        "content": "Approved by security team",
        "author_id": "user_xyz",
        "created_at": "2025-01-14T10:00:00Z"
      }
    ],
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-15T14:30:00Z"
  }
}
```

## Update Item

Update an existing item. Supports partial updates.

```http
PATCH /v1/items/{id}
```

### Request Body

All fields are optional. Only provided fields are updated.

### Request

```bash
curl -X PATCH "https://api.tracertm.dev/v1/items/item_abc123" \
  -H "Authorization: Bearer $TRACERTM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 5" \
  -d '{
    "priority": "critical",
    "custom_fields": {
      "story_points": 21
    },
    "tags": ["security", "mvp", "urgent"]
  }'
```

### Optimistic Locking

Use `If-Match` header with version number to prevent conflicts:

```bash
# Get current version
item = GET /v1/items/item_abc123  # version: 5

# Update with version check
PATCH /v1/items/item_abc123
If-Match: 5

# If version changed, returns 409 Conflict
```

### Response

```json
{
  "data": {
    "id": "item_abc123",
    "title": "User Authentication",
    "priority": "critical",
    "custom_fields": {
      "platform": ["web", "mobile"],
      "component": "auth",
      "story_points": 21
    },
    "tags": ["security", "mvp", "urgent"],
    "version": 6,
    "updated_at": "2025-01-15T16:30:00Z"
  }
}
```

## Delete Item

Delete an item. Soft delete by default.

```http
DELETE /v1/items/{id}
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `permanent` | boolean | Permanently delete (default: false) |
| `cascade` | boolean | Delete children items (default: false) |

### Request

```bash
# Soft delete
curl -X DELETE "https://api.tracertm.dev/v1/items/item_abc123" \
  -H "Authorization: Bearer $TRACERTM_API_KEY"

# Permanent delete with children
curl -X DELETE "https://api.tracertm.dev/v1/items/item_abc123?permanent=true&cascade=true" \
  -H "Authorization: Bearer $TRACERTM_API_KEY"
```

## Item History

Get version history for an item.

```http
GET /v1/items/{id}/history
```

### Response

```json
{
  "data": [
    {
      "version": 5,
      "changes": {
        "status": {"from": "review", "to": "approved"},
        "priority": {"from": "medium", "to": "high"}
      },
      "changed_by": "user_xyz789",
      "changed_at": "2025-01-15T14:30:00Z",
      "comment": "Approved after security review"
    },
    {
      "version": 4,
      "changes": {
        "description": {"from": "...", "to": "..."}
      },
      "changed_by": "user_abc123",
      "changed_at": "2025-01-14T10:00:00Z"
    }
  ]
}
```

## Transition Status

Transition item to a new status (workflow-aware).

```http
POST /v1/items/{id}/transition
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | string | Yes | Target status |
| `comment` | string | No | Transition comment |
| `resolution` | string | No | Resolution (for closed statuses) |

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/items/item_abc123/transition" \
  -H "Authorization: Bearer $TRACERTM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "comment": "Reviewed and approved by product team"
  }'
```

### Response

```json
{
  "data": {
    "id": "item_abc123",
    "status": "approved",
    "previous_status": "review",
    "transitioned_at": "2025-01-15T16:45:00Z",
    "transitioned_by": "user_xyz789"
  }
}
```

## Bulk Operations

See [Batch Operations](/docs/api-reference/rest-api/batch-operations) for bulk item operations.

```python
# Bulk create items
items = await client.items.bulk_create(
    project_id="proj_456",
    items=[
        {"type": "requirement", "title": "Req 1"},
        {"type": "requirement", "title": "Req 2"},
        {"type": "requirement", "title": "Req 3"}
    ]
)

# Bulk update
await client.items.bulk_update(
    items=[
        {"id": "item_1", "status": "approved"},
        {"id": "item_2", "status": "approved"}
    ]
)
```

## Related Documentation

- [List Items](/docs/api-reference/rest-api/items-list) - Detailed list endpoint
- [Create Item](/docs/api-reference/rest-api/items-create) - Detailed create endpoint
- [Update Item](/docs/api-reference/rest-api/items-update) - Update operations
- [Links API](/docs/api-reference/rest-api/links) - Traceability links
- [Workflows API](/docs/api-reference/rest-api/workflows) - Status workflows

