---
title: "REST API Overview"
description: "Complete overview of the TraceRTM REST API - endpoints, authentication, and usage"
keywords: [rest api, api, endpoints, http, json]
---

# REST API Overview

The TraceRTM REST API provides programmatic access to all TraceRTM features through standard HTTP methods and JSON responses.

## Base URL

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

For self-hosted instances:

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

## Authentication

All API requests require authentication. Include your credentials in the request headers:

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

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

👉 [Authentication Guide](/docs/api-reference/authentication)

## Request Format

### Headers

```http
Authorization: Bearer <token>
# or
X-API-Key: <api-key>
Content-Type: application/json
Accept: application/json
```

### Request Body

```json
{
  "field": "value",
  "nested": {
    "key": "value"
  }
}
```

## Response Format

### Success Response

```json
{
  "data": {
    "id": "item_abc123",
    "title": "Example Item"
  },
  "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
  }
}
```

### Error Response

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

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| `200` | Success |
| `201` | Created |
| `204` | No Content (successful delete) |
| `400` | Bad Request |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found |
| `409` | Conflict |
| `422` | Unprocessable Entity |
| `429` | Rate Limited |
| `500` | Server Error |

## Core Resources

### Projects

Manage TraceRTM projects:

- `GET /api/v1/projects` - List projects
- `POST /api/v1/projects` - Create project
- `GET /api/v1/projects/{id}` - Get project
- `PUT /api/v1/projects/{id}` - Update project
- `DELETE /api/v1/projects/{id}` - Delete project

👉 [Projects API](./02-artifacts)

### Items (Artifacts)

Manage requirements, test cases, and artifacts:

- `GET /api/v1/items` - List items
- `POST /api/v1/items` - Create item
- `GET /api/v1/items/{id}` - Get item
- `DELETE /api/v1/items/{id}` - Delete item

👉 [Items API](./02-artifacts)

### Links

Manage traceability relationships:

- `GET /api/v1/links` - List links
- `PUT /api/v1/links/{id}` - Update link

👉 [Links API](./04-relationships)

### Analysis

Advanced analysis endpoints:

- `GET /api/v1/analysis/impact/{item_id}` - Impact analysis
- `GET /api/v1/analysis/cycles/{project_id}` - Cycle detection
- `GET /api/v1/analysis/shortest-path` - Shortest path

👉 [Analysis Endpoints](./05-metadata)

### Search

Search and query endpoints:

- `POST /api/v1/projects/{id}/search/advanced` - Advanced search

👉 [Search API](./06-search)

### Export/Import

Data export and import:

- `GET /api/v1/projects/{id}/export` - Export project
- `POST /api/v1/projects/{id}/import` - Import data

### Sync

Synchronization endpoints:

- `GET /api/v1/projects/{id}/sync/status` - Sync status
- `POST /api/v1/projects/{id}/sync` - Execute sync

### Graph

Graph query endpoints:

- `GET /api/v1/projects/{id}/graph/neighbors` - Get neighbors

## Pagination

List endpoints support pagination:

```bash
# Offset-based
GET /api/v1/items?skip=0&limit=50

# Response includes pagination info
{
  "total": 150,
  "items": [...],
  "has_more": true
}
```

## Filtering

Filter results using query parameters:

```bash
# Filter by status
GET /api/v1/items?status=active

# Multiple filters
GET /api/v1/items?status=active&view=requirements
```

## Rate Limiting

API requests are rate-limited. Check response headers:

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

👉 [Rate Limiting Guide](/docs/api-reference/authentication/rate-limiting)

## SDKs

Official SDKs are available:

- [Python SDK](/docs/api-reference/sdks/python)
- [JavaScript SDK](/docs/api-reference/sdks/javascript)
- [Go SDK](/docs/api-reference/sdks/go)

## Next Steps

- [Authentication](/docs/api-reference/authentication) - Set up authentication
- [Projects API](./02-artifacts) - Manage projects
- [Items API](./02-artifacts) - Manage artifacts
- [Error Handling](./12-error-handling) - Handle API errors
