---
title: "REST API"
description: "Complete REST API reference for TraceRTM - endpoints, authentication, and usage examples"
---

# REST API

The TraceRTM REST API provides programmatic access to all TraceRTM features. Build integrations, automate workflows, and extend TraceRTM's capabilities using standard HTTP methods.

## API Quick Reference

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         TraceRTM REST API                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Base URL: https://api.tracertm.dev/v1                                     │
│                                                                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│   │  Projects   │  │    Items    │  │    Links    │  │  Workflows  │       │
│   │  /projects  │  │   /items    │  │   /links    │  │ /workflows  │       │
│   └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
│                                                                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│   │   Search    │  │   Batch     │  │  Webhooks   │  │   Reports   │       │
│   │  /search    │  │   /batch    │  │ /webhooks   │  │  /reports   │       │
│   └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Base URL

All API requests are made to:

```
https://api.tracertm.dev/v1
```

For self-hosted instances:

```
https://your-domain.com/api/v1
```

## Authentication

Include your API key or access token in the `Authorization` header:

```bash
# Using API Key
curl -H "Authorization: Bearer rtm_live_abc123..." \
  https://api.tracertm.dev/v1/projects

# Using JWT Access Token
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  https://api.tracertm.dev/v1/projects
```

See [Authentication](/docs/api-reference/authentication) for detailed auth options.

## Quick Start

### List Projects

```bash
curl -X GET "https://api.tracertm.dev/v1/projects" \
  -H "Authorization: Bearer $TRACERTM_API_KEY" \
  -H "Content-Type: application/json"
```

### Create an Item

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_123/items" \
  -H "Authorization: Bearer $TRACERTM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "requirement",
    "title": "User Authentication",
    "description": "System must support OAuth 2.0 authentication",
    "priority": "high",
    "status": "draft"
  }'
```

### Create a Traceability Link

```bash
curl -X POST "https://api.tracertm.dev/v1/links" \
  -H "Authorization: Bearer $TRACERTM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "item_req_001",
    "target_id": "item_test_001",
    "link_type": "verified_by",
    "metadata": {
      "confidence": 0.95
    }
  }'
```

## Endpoint Categories

### [Projects](/docs/api-reference/rest-api/projects)
Manage TraceRTM projects, settings, and team access.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/projects` | List all projects |
| `POST` | `/projects` | Create a project |
| `GET` | `/projects/{id}` | Get project details |
| `PATCH` | `/projects/{id}` | Update a project |
| `DELETE` | `/projects/{id}` | Delete a project |

### [Items](/docs/api-reference/rest-api/items)
Create and manage requirements, test cases, and other traceable items.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/projects/{id}/items` | List items in project |
| `POST` | `/projects/{id}/items` | Create an item |
| `GET` | `/items/{id}` | Get item details |
| `PATCH` | `/items/{id}` | Update an item |
| `DELETE` | `/items/{id}` | Delete an item |

### [Links](/docs/api-reference/rest-api/links)
Establish and query traceability relationships between items.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/links` | List all links |
| `POST` | `/links` | Create a link |
| `GET` | `/links/{id}` | Get link details |
| `DELETE` | `/links/{id}` | Delete a link |
| `GET` | `/items/{id}/links` | Get item's links |

### [Workflows](/docs/api-reference/rest-api/workflows)
Define and execute item status workflows.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/workflows` | List workflows |
| `POST` | `/workflows` | Create a workflow |
| `POST` | `/items/{id}/transition` | Transition item status |

### [Search](/docs/api-reference/rest-api/search)
Full-text and structured search across items.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/search` | Simple search |
| `POST` | `/search` | Advanced search |
| `POST` | `/search/semantic` | AI-powered semantic search |

### [Batch Operations](/docs/api-reference/rest-api/batch-operations)
Perform bulk operations efficiently.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/batch` | Execute batch operations |
| `POST` | `/import` | Bulk import items |
| `POST` | `/export` | Export project data |

### [Webhooks](/docs/api-reference/rest-api/webhooks)
Subscribe to TraceRTM events.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/webhooks` | List webhooks |
| `POST` | `/webhooks` | Create a webhook |
| `DELETE` | `/webhooks/{id}` | Delete a webhook |

## Request Format

### Headers

```http
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
X-Request-ID: <optional-request-id>
```

### Request Body

```json
{
  "field": "value",
  "nested": {
    "key": "value"
  },
  "array": ["item1", "item2"]
}
```

## Response Format

### Success Response

```json
{
  "data": {
    "id": "item_abc123",
    "type": "requirement",
    "title": "User Authentication",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}
```

### List Response

```json
{
  "data": [
    {"id": "item_001", "title": "Item 1"},
    {"id": "item_002", "title": "Item 2"}
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "has_more": true
  },
  "links": {
    "self": "/v1/items?page=1",
    "next": "/v1/items?page=2",
    "prev": null
  }
}
```

### Error Response

```json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ]
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}
```

## HTTP Status Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `201` | Created |
| `204` | No Content (successful delete) |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid or missing auth |
| `403` | Forbidden - Insufficient permissions |
| `404` | Not Found - Resource doesn't exist |
| `409` | Conflict - Version conflict |
| `422` | Unprocessable Entity - Validation error |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Internal Server Error |

## Rate Limiting

API requests are rate limited per API key:

| Plan | Requests/minute | Requests/day |
|------|-----------------|--------------|
| Free | 60 | 1,000 |
| Pro | 300 | 50,000 |
| Enterprise | 1,000 | Unlimited |

Rate limit headers are included in every response:

```http
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1704067200
```

## Pagination

List endpoints support pagination:

```bash
# Offset-based pagination
curl "https://api.tracertm.dev/v1/items?page=2&per_page=50"

# Cursor-based pagination (recommended for large datasets)
curl "https://api.tracertm.dev/v1/items?cursor=eyJpZCI6MTAwfQ&limit=50"
```

## Filtering

Filter results using query parameters:

```bash
# Filter by status
curl "https://api.tracertm.dev/v1/items?status=active"

# Filter by type
curl "https://api.tracertm.dev/v1/items?type=requirement"

# Multiple filters
curl "https://api.tracertm.dev/v1/items?status=active&priority=high&type=requirement"

# Date range
curl "https://api.tracertm.dev/v1/items?created_after=2025-01-01&created_before=2025-02-01"
```

## Sorting

Sort results using the `sort` parameter:

```bash
# Sort by created date (ascending)
curl "https://api.tracertm.dev/v1/items?sort=created_at"

# Sort descending (prefix with -)
curl "https://api.tracertm.dev/v1/items?sort=-created_at"

# Multiple sort fields
curl "https://api.tracertm.dev/v1/items?sort=-priority,created_at"
```

## SDKs and Libraries

Official SDKs are available for common languages:

- [Python SDK](/sdk/python) - `pip install tracertm`
- [JavaScript/TypeScript SDK](/sdk/javascript) - `npm install @tracertm/sdk`
- [Go SDK](/sdk/go) - `go get github.com/tracertm/tracertm-go`

## API Changelog

See [API Versioning](/docs/api-reference/rest-api/versioning) for version history and migration guides.

## Related Documentation

- [Authentication](/docs/api-reference/authentication) - Auth methods
- [Rate Limiting](/docs/api-reference/rest-api/rate-limiting) - Rate limit details
- [Errors](/docs/api-reference/rest-api/errors) - Error handling
- [Webhooks](/docs/api-reference/rest-api/webhooks) - Event subscriptions

