---
title: "Export & Import API"
description: "Export project data to various formats and import data into projects"
keywords: [export, import, batch, data migration, json, csv, markdown]
---

# Export & Import API

The Export & Import API allows you to export project data to various formats and import data into projects for backup, migration, or integration purposes.

## Export Project

Export project data to JSON, CSV, or Markdown format.

### Endpoint

```
GET /api/v1/projects/{project_id}/export
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID to export |

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `format` | string | No | Export format: `json`, `csv`, or `markdown` (default: `json`) |

### Request Example

```bash
# Export as JSON
curl -X GET "https://api.tracertm.dev/v1/projects/proj_123/export?format=json" \
  -H "Authorization: Bearer $TOKEN" \
  -o project_export.json

# Export as CSV
curl -X GET "https://api.tracertm.dev/v1/projects/proj_123/export?format=csv" \
  -H "Authorization: Bearer $TOKEN" \
  -o project_export.csv

# Export as Markdown
curl -X GET "https://api.tracertm.dev/v1/projects/proj_123/export?format=markdown" \
  -H "Authorization: Bearer $TOKEN" \
  -o project_export.md
```

### Response (JSON Format)

```json
{
  "project": {
    "id": "proj_123",
    "name": "Authentication System",
    "description": "OAuth 2.0 implementation"
  },
  "items": [
    {
      "id": "item_001",
      "title": "Requirement 1",
      "view": "requirements",
      "status": "active"
    }
  ],
  "links": [
    {
      "id": "link_001",
      "source_id": "item_001",
      "target_id": "item_002",
      "type": "verified_by"
    }
  ],
  "exported_at": "2025-01-20T10:30:00Z"
}
```

### Python Example

```python
from tracertm import TraceRTM

client = TraceRTM(api_key="rtm_live_abc123...")

# Export as JSON
export_data = client.projects.export(
    project_id="proj_123",
    format="json"
)

# Save to file
import json
with open("project_export.json", "w") as f:
    json.dump(export_data, f, indent=2)

# Export as CSV
csv_data = client.projects.export(
    project_id="proj_123",
    format="csv"
)

with open("project_export.csv", "w") as f:
    f.write(csv_data)
```

## Import Project

Import project data from JSON or CSV format.

### Endpoint

```
POST /api/v1/projects/{project_id}/import
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID to import into |

### Request Body

```json
{
  "format": "json",
  "data": "{...exported JSON data...}"
}
```

### Request Example

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_123/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "data": "{\"items\":[...],\"links\":[...]}"
  }'
```

### Response

```json
{
  "imported": {
    "items": 50,
    "links": 75
  },
  "errors": [],
  "imported_at": "2025-01-20T10:35:00Z"
}
```

### Python Example

```python
# Read exported data
with open("project_export.json", "r") as f:
    export_data = json.load(f)

# Import into project
result = client.projects.import_data(
    project_id="proj_123",
    format="json",
    data=json.dumps(export_data)
)

print(f"Imported {result.imported.items} items")
print(f"Imported {result.imported.links} links")

if result.errors:
    print(f"Errors: {result.errors}")
```

## Export Formats

### JSON Format

Structured JSON with all project data:

```json
{
  "project": {...},
  "items": [...],
  "links": [...],
  "workflows": [...],
  "metadata": {...}
}
```

**Use cases**: Backup, migration, programmatic processing

### CSV Format

Tabular format for spreadsheet applications:

```csv
id,title,view,status,created_at
item_001,Requirement 1,requirements,active,2025-01-15
item_002,Test Case 1,test-cases,draft,2025-01-16
```

**Use cases**: Spreadsheet analysis, reporting, Excel import

### Markdown Format

Human-readable Markdown documentation:

```markdown
# Authentication System

## Items

### Requirement 1
- ID: item_001
- Status: active
- View: requirements

## Links

- item_001 --[verified_by]--> item_002
```

**Use cases**: Documentation, reports, sharing

## Import Validation

The import process validates data:

- **Item validation**: Required fields, valid statuses
- **Link validation**: Valid source/target items, link types
- **Reference integrity**: Items referenced by links must exist

### Import Errors

```json
{
  "imported": {
    "items": 45,
    "links": 70
  },
  "errors": [
    {
      "type": "validation_error",
      "item_id": "item_001",
      "message": "Invalid status: invalid_status"
    },
    {
      "type": "reference_error",
      "link_id": "link_001",
      "message": "Source item not found: item_missing"
    }
  ]
}
```

## Best Practices

### 1. Regular Backups

Export projects regularly:

```python
import schedule
import time

def backup_project(project_id):
    export_data = client.projects.export(project_id, format="json")
    filename = f"backup_{project_id}_{datetime.now().isoformat()}.json"
    with open(filename, "w") as f:
        json.dump(export_data, f)
    print(f"Backed up to {filename}")

# Schedule daily backups
schedule.every().day.at("02:00").do(backup_project, "proj_123")
```

### 2. Validate Before Import

Validate export data before importing:

```python
def validate_export_data(data):
    errors = []
    
    # Check required fields
    if "items" not in data:
        errors.append("Missing items array")
    
    # Validate items
    for item in data.get("items", []):
        if "id" not in item:
            errors.append(f"Item missing ID: {item}")
    
    return errors

# Validate before import
errors = validate_export_data(export_data)
if errors:
    print(f"Validation errors: {errors}")
else:
    client.projects.import_data("proj_123", "json", json.dumps(export_data))
```

### 3. Handle Import Errors

Process import results carefully:

```python
result = client.projects.import_data("proj_123", "json", data)

if result.errors:
    print(f"Import completed with {len(result.errors)} errors:")
    for error in result.errors:
        print(f"  - {error.type}: {error.message}")
    
    # Retry failed items
    retry_failed_items(result.errors)
else:
    print("Import completed successfully")
```

## Error Responses

### Unsupported Format

```json
{
  "error": {
    "code": "validation_error",
    "message": "Unsupported format: xml. Supported formats: json, csv, markdown"
  }
}
```

### Import Validation Error

```json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid import data",
    "details": [
      {
        "field": "items[0].status",
        "message": "Invalid status value"
      }
    ]
  }
}
```

## Related Documentation

- [Projects API](./01-projects) - Project management
- [Items API](./02-artifacts) - Item management
- [Links API](./04-relationships) - Link management
