---
title: "Base URL & Endpoints"
description: "TraceRTM API base URLs, endpoint conventions, and environment configuration"
---

# Base URL & Endpoints

This guide covers TraceRTM API base URLs for different environments and endpoint naming conventions.

## Base URLs

### Production API

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

### Regional Endpoints

For data residency requirements:

| Region | Base URL |
|--------|----------|
| **US (Default)** | `https://api.tracertm.dev/v1` |
| **EU (Frankfurt)** | `https://api.eu.tracertm.dev/v1` |
| **APAC (Singapore)** | `https://api.ap.tracertm.dev/v1` |
| **AU (Sydney)** | `https://api.au.tracertm.dev/v1` |

### Self-Hosted Instances

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

Or with custom port:

```
https://tracertm.internal.company.com:8443/api/v1
```

### Development & Testing

| Environment | Base URL |
|-------------|----------|
| **Sandbox** | `https://sandbox-api.tracertm.dev/v1` |
| **Staging** | `https://staging-api.tracertm.dev/v1` |
| **Local** | `http://localhost:8000/api/v1` |

## Environment Configuration

### Python SDK

```python
from tracertm import TraceRTMClient

# Production (default)
client = TraceRTMClient(api_key="rtm_live_...")

# EU region
client = TraceRTMClient(
    api_key="rtm_live_...",
    base_url="https://api.eu.tracertm.dev/v1"
)

# Self-hosted
client = TraceRTMClient(
    api_key="rtm_live_...",
    base_url="https://tracertm.company.com/api/v1"
)

# Sandbox for testing
client = TraceRTMClient(
    api_key="rtm_test_...",
    base_url="https://sandbox-api.tracertm.dev/v1"
)
```

### JavaScript SDK

```typescript
import { TraceRTMClient } from '@tracertm/sdk'

// Production (default)
const client = new TraceRTMClient({
  apiKey: 'rtm_live_...'
})

// EU region
const client = new TraceRTMClient({
  apiKey: 'rtm_live_...',
  baseUrl: 'https://api.eu.tracertm.dev/v1'
})

// Self-hosted
const client = new TraceRTMClient({
  apiKey: 'rtm_live_...',
  baseUrl: 'https://tracertm.company.com/api/v1'
})
```

### Environment Variables

```bash
# .env file
TRACERTM_API_KEY=rtm_live_abc123...
TRACERTM_BASE_URL=https://api.tracertm.dev/v1

# EU region
TRACERTM_BASE_URL=https://api.eu.tracertm.dev/v1

# Self-hosted
TRACERTM_BASE_URL=https://tracertm.company.com/api/v1
```

### CLI Configuration

```bash
# Configure default endpoint
rtm config set api.base_url https://api.tracertm.dev/v1

# Use profile for different environments
rtm config set --profile eu api.base_url https://api.eu.tracertm.dev/v1
rtm config set --profile staging api.base_url https://staging-api.tracertm.dev/v1

# Use specific profile
rtm --profile eu projects list
```

## Endpoint Structure

### URL Pattern

```
{base_url}/{version}/{resource}/{id?}/{sub-resource?}
```

### Examples

```
GET    /v1/projects                    # List projects
POST   /v1/projects                    # Create project
GET    /v1/projects/proj_123           # Get project
PATCH  /v1/projects/proj_123           # Update project
DELETE /v1/projects/proj_123           # Delete project

GET    /v1/projects/proj_123/items     # List project items
POST   /v1/projects/proj_123/items     # Create item in project
GET    /v1/items/item_456              # Get item directly
PATCH  /v1/items/item_456              # Update item
DELETE /v1/items/item_456              # Delete item

GET    /v1/items/item_456/links        # Get item's links
POST   /v1/links                       # Create a link
DELETE /v1/links/link_789              # Delete a link
```

## Resource Endpoints

### Core Resources

| Resource | Endpoint | Description |
|----------|----------|-------------|
| Projects | `/v1/projects` | Project management |
| Items | `/v1/items` | Requirements, tests, etc. |
| Links | `/v1/links` | Traceability relationships |
| Workflows | `/v1/workflows` | Status workflows |

### Project-Scoped Resources

| Resource | Endpoint | Description |
|----------|----------|-------------|
| Project Items | `/v1/projects/{id}/items` | Items in a project |
| Project Members | `/v1/projects/{id}/members` | Project team |
| Project Settings | `/v1/projects/{id}/settings` | Project configuration |
| Project Exports | `/v1/projects/{id}/exports` | Data exports |

### User Resources

| Resource | Endpoint | Description |
|----------|----------|-------------|
| Current User | `/v1/me` | Authenticated user info |
| Users | `/v1/users` | User management (admin) |
| Teams | `/v1/teams` | Team management |

### System Resources

| Resource | Endpoint | Description |
|----------|----------|-------------|
| Search | `/v1/search` | Full-text search |
| Batch | `/v1/batch` | Bulk operations |
| Webhooks | `/v1/webhooks` | Event subscriptions |
| API Keys | `/v1/api-keys` | API key management |

## Special Endpoints

### Health Check

```bash
# No authentication required
curl https://api.tracertm.dev/health

# Response
{
  "status": "healthy",
  "version": "1.5.0",
  "region": "us-east-1"
}
```

### OpenAPI Specification

```bash
# Get OpenAPI spec
curl https://api.tracertm.dev/openapi.json

# Swagger UI
open https://api.tracertm.dev/docs

# ReDoc
open https://api.tracertm.dev/redoc
```

### Well-Known Endpoints

```bash
# OAuth discovery
curl https://auth.tracertm.dev/.well-known/oauth-authorization-server

# JWKS (for JWT validation)
curl https://auth.tracertm.dev/.well-known/jwks.json

# OpenID Configuration
curl https://auth.tracertm.dev/.well-known/openid-configuration
```

## URL Construction

### Building URLs Programmatically

```python
from urllib.parse import urljoin, urlencode

BASE_URL = "https://api.tracertm.dev/v1"

def build_url(resource: str, resource_id: str = None, **params) -> str:
    """Build API URL with proper encoding."""
    path = f"/{resource}"
    if resource_id:
        path = f"{path}/{resource_id}"

    url = urljoin(BASE_URL, path)

    if params:
        url = f"{url}?{urlencode(params)}"

    return url

# Examples
build_url("projects")
# -> https://api.tracertm.dev/v1/projects

build_url("items", "item_123")
# -> https://api.tracertm.dev/v1/items/item_123

build_url("items", page=2, per_page=50, status="active")
# -> https://api.tracertm.dev/v1/items?page=2&per_page=50&status=active
```

### TypeScript URL Builder

```typescript
class APIUrlBuilder {
  constructor(private baseUrl: string) {}

  build(
    resource: string,
    id?: string,
    params?: Record<string, string | number>
  ): string {
    let url = `${this.baseUrl}/${resource}`
    if (id) url += `/${id}`

    if (params) {
      const searchParams = new URLSearchParams()
      for (const [key, value] of Object.entries(params)) {
        searchParams.append(key, String(value))
      }
      url += `?${searchParams.toString()}`
    }

    return url
  }
}

const api = new APIUrlBuilder('https://api.tracertm.dev/v1')

api.build('projects')
// -> https://api.tracertm.dev/v1/projects

api.build('items', 'item_123', { include: 'links' })
// -> https://api.tracertm.dev/v1/items/item_123?include=links
```

## ID Formats

TraceRTM uses prefixed IDs for clarity:

| Resource | Prefix | Example |
|----------|--------|---------|
| Project | `proj_` | `proj_abc123xyz` |
| Item | `item_` | `item_def456uvw` |
| Link | `link_` | `link_ghi789rst` |
| User | `user_` | `user_jkl012opq` |
| Team | `team_` | `team_mno345lmn` |
| Workflow | `wf_` | `wf_pqr678ijk` |
| Webhook | `wh_` | `wh_stu901fgh` |
| API Key | `rtm_` | `rtm_live_abc123` |

### ID Validation Regex

```regex
^(proj|item|link|user|team|wf|wh)_[a-zA-Z0-9]{12,}$
```

## Trailing Slashes

The API is lenient with trailing slashes:

```bash
# Both work identically
GET /v1/projects
GET /v1/projects/
```

However, for consistency, we recommend **omitting** trailing slashes.

## Case Sensitivity

- **URLs**: Case-insensitive for paths, case-sensitive for IDs
- **Query Parameters**: Case-insensitive for names
- **JSON Fields**: Case-sensitive (use snake_case)

```bash
# These are equivalent
GET /v1/Projects
GET /v1/projects

# But IDs are case-sensitive
GET /v1/items/Item_ABC  # Different from item_abc
GET /v1/items/item_abc
```

## Related Documentation

- [API Overview](/docs/api-reference/rest-api/overview) - API introduction
- [Authentication](/docs/api-reference/authentication) - Auth methods
- [Versioning](/docs/api-reference/rest-api/versioning) - API versions

