---
title: API Versions
description: Complete changelog of TraceRTM API versions with detailed release notes
---

# API Versions

This page documents all TraceRTM API versions, their release dates, and detailed changelogs.

## Version Overview

| Version | Status | Released | Deprecated | Sunset |
|---------|--------|----------|------------|--------|
| v1 | **Current** | 2023-06-01 | — | — |

---

## v1 (Current)

### Date Version: 2024-12-01 (Latest)

Released: December 1, 2024

#### New Features

- **Filter Expressions**: Complex AND/OR/NOT filter logic via POST body
- **Nested Filters**: Multi-level nested filter conditions
- **Filter Templates**: Save and reuse filter configurations

#### New Endpoints

```
POST /v1/projects/{project_id}/items/query
GET  /v1/projects/{project_id}/filter-templates
POST /v1/projects/{project_id}/filter-templates
```

#### New Parameters

| Endpoint | Parameter | Description |
|----------|-----------|-------------|
| `GET /items` | `filter_template` | Apply saved filter template |
| `POST /items/query` | `filter` | Complex filter expression |

#### Example

```bash
# Complex filter with OR logic
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/items/query" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "or": [
        {"priority": {"eq": "critical"}},
        {"and": [
          {"priority": {"eq": "high"}},
          {"due_date": {"lt": "now+7d"}}
        ]}
      ]
    }
  }'
```

---

### Date Version: 2024-09-01

Released: September 1, 2024

#### New Features

- **Multi-Sort**: Sort by multiple fields with independent directions
- **Null Handling**: Control null value positioning per sort field
- **Stable Sort**: Guaranteed deterministic ordering

#### New Parameters

| Endpoint | Parameter | Description |
|----------|-----------|-------------|
| `GET /items` | `sort` (multiple) | Comma-separated sort fields |
| `GET /items` | `order` (multiple) | Comma-separated sort directions |
| `GET /items` | `nulls` | Null value positioning |

#### Example

```bash
# Multi-sort: priority desc, then due_date asc
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?sort=priority,due_date,id&order=desc,asc,asc&nulls=last,last,last"
```

#### Response Changes

Sort information now includes all fields:

```json
{
  "sort": [
    {"field": "priority", "order": "desc", "nulls": "last"},
    {"field": "due_date", "order": "asc", "nulls": "last"},
    {"field": "id", "order": "asc", "nulls": "last"}
  ]
}
```

---

### Date Version: 2024-06-01

Released: June 1, 2024

#### New Features

- **Cursor Pagination**: Efficient, consistent pagination for large datasets
- **Bidirectional Navigation**: Navigate forward and backward through results
- **Cursor Expiration**: 1-hour cursor validity with clear error handling

#### New Endpoints

```
GET /v1/projects/{project_id}/items (cursor support)
GET /v1/links (cursor support)
```

#### New Parameters

| Endpoint | Parameter | Description |
|----------|-----------|-------------|
| `GET /items` | `cursor` | Pagination cursor |
| `GET /items` | `direction` | `next` or `prev` |

#### Response Changes

New pagination format:

```json
{
  "pagination": {
    "has_next": true,
    "has_prev": false,
    "next_cursor": "eyJpZCI6Iml...",
    "prev_cursor": null,
    "cursors": {
      "first": "eyJpZCI6Iml...",
      "current": "eyJpZCI6Iml..."
    }
  }
}
```

#### Migration Notes

- Offset pagination still supported
- Cursor pagination recommended for datasets > 1000 items
- Cursors encode sort order; use same sort params when paginating

---

### Date Version: 2024-03-01

Released: March 1, 2024

#### New Features

- **Batch Operations**: Create, update, delete multiple items in one request
- **Bulk Import**: Import items from CSV/JSON files
- **Async Processing**: Long-running operations with status tracking

#### New Endpoints

```
POST /v1/projects/{project_id}/items/batch
POST /v1/projects/{project_id}/items/import
GET  /v1/projects/{project_id}/jobs/{job_id}
POST /v1/projects/{project_id}/links/batch
```

#### Batch Limits

| Plan | Max Batch Size | Max Import Size |
|------|----------------|-----------------|
| Free | 50 items | 100 items |
| Pro | 200 items | 1,000 items |
| Enterprise | 1,000 items | 10,000 items |

#### Example

```bash
# Batch create items
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/items/batch" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {"method": "create", "data": {"type": "requirement", "title": "Item 1"}},
      {"method": "create", "data": {"type": "requirement", "title": "Item 2"}},
      {"method": "update", "id": "item_req_001", "data": {"status": "approved"}}
    ]
  }'
```

---

### Date Version: 2024-01-15 (Initial Release)

Released: January 15, 2024

#### Core Features

- **Projects API**: Create, read, update, delete projects
- **Items API**: Full item lifecycle management
- **Links API**: Traceability link management
- **Workflows API**: Status transitions and approvals
- **Search API**: Full-text and filtered search
- **Webhooks API**: Event notifications

#### Authentication

- API Key authentication (Bearer token)
- Test and Live key modes
- Agent API keys for automation

#### Rate Limits

| Plan | Rate Limit |
|------|------------|
| Free | 60 requests/minute |
| Pro | 300 requests/minute |
| Enterprise | 1,000 requests/minute |

#### Endpoints

**Projects**
```
GET    /v1/projects
POST   /v1/projects
GET    /v1/projects/{project_id}
PATCH  /v1/projects/{project_id}
DELETE /v1/projects/{project_id}
```

**Items**
```
GET    /v1/projects/{project_id}/items
POST   /v1/projects/{project_id}/items
GET    /v1/projects/{project_id}/items/{item_id}
PATCH  /v1/projects/{project_id}/items/{item_id}
DELETE /v1/projects/{project_id}/items/{item_id}
```

**Links**
```
GET    /v1/projects/{project_id}/links
POST   /v1/projects/{project_id}/links
GET    /v1/projects/{project_id}/links/{link_id}
DELETE /v1/projects/{project_id}/links/{link_id}
GET    /v1/projects/{project_id}/items/{item_id}/links
```

**Workflows**
```
GET    /v1/projects/{project_id}/workflows
POST   /v1/projects/{project_id}/items/{item_id}/transitions
GET    /v1/projects/{project_id}/items/{item_id}/history
```

**Search**
```
GET    /v1/projects/{project_id}/search
POST   /v1/projects/{project_id}/search
```

**Webhooks**
```
GET    /v1/webhooks
POST   /v1/webhooks
GET    /v1/webhooks/{webhook_id}
PATCH  /v1/webhooks/{webhook_id}
DELETE /v1/webhooks/{webhook_id}
```

---

## Upcoming Features

### v1 Roadmap (Date Versions)

| Target Date | Feature | Description |
|-------------|---------|-------------|
| 2025-03-01 | GraphQL API | Alternative GraphQL interface |
| 2025-06-01 | Real-time Subscriptions | WebSocket event streaming |
| 2025-09-01 | Advanced Analytics | Query analytics data |

### v2 Preview (Planned)

Expected features for v2:

- **Unified Resource Model**: Simplified item/link structure
- **Enhanced Permissions**: Fine-grained field-level access
- **Native Markdown**: Rich text with Markdown support
- **Improved Relationships**: Bidirectional link tracking

---

## Version Comparison

### Feature Availability by Date Version

| Feature | 2024-01-15 | 2024-03-01 | 2024-06-01 | 2024-09-01 | 2024-12-01 |
|---------|------------|------------|------------|------------|------------|
| Core CRUD | ✓ | ✓ | ✓ | ✓ | ✓ |
| Search | ✓ | ✓ | ✓ | ✓ | ✓ |
| Webhooks | ✓ | ✓ | ✓ | ✓ | ✓ |
| Batch Operations | — | ✓ | ✓ | ✓ | ✓ |
| Bulk Import | — | ✓ | ✓ | ✓ | ✓ |
| Cursor Pagination | — | — | ✓ | ✓ | ✓ |
| Multi-Sort | — | — | — | ✓ | ✓ |
| Filter Expressions | — | — | — | — | ✓ |

### Response Format Changes

#### Items Response

**2024-01-15:**
```json
{
  "data": [...],
  "total": 156,
  "limit": 20,
  "offset": 0
}
```

**2024-06-01:**
```json
{
  "data": [...],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "has_more": true,
    "next_cursor": "eyJ..."
  }
}
```

**2024-09-01:**
```json
{
  "data": [...],
  "sort": [
    {"field": "priority", "order": "desc"}
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJ..."
  }
}
```

---

## Checking Your Version

### API Response

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

Response headers:
```http
X-API-Version: v1
X-API-Date-Version: 2024-12-01
```

### SDK Version

```python
import tracertm
print(f"SDK: {tracertm.__version__}")
print(f"API: {tracertm.API_VERSION}")
print(f"Date: {tracertm.API_DATE_VERSION}")
```

---

## Related Documentation

- [API Versioning](/docs/api-reference/rest-api/versioning) - Versioning strategy
- [Deprecations](/docs/api-reference/rest-api/deprecations) - Deprecation notices
- [Migration Guide](/docs/api-reference/rest-api/migration-guide) - Migration instructions
