# API Versioning Fix Design

## Problem

Server URL is hardcoded to `https://api.alteg.io/api/v1`, causing V2 paths like `/api/v2/companies/{id}/tags` to resolve incorrectly as `/api/v1/api/v2/...`.

## Solution

Change base URL to `https://api.alteg.io/api` and use explicit version prefixes in all paths.

## Changes

### 1. Server URL

```yaml
# Before
servers:
  - url: 'https://api.alteg.io/api/v1'

# After
servers:
  - url: 'https://api.alteg.io/api'
```

### 2. V1 Paths (~120 paths)

Add `/v1` prefix to all existing paths:

```yaml
# Before
'/companies':
'/auth':
'/company/{location_id}':

# After
'/v1/companies':
'/v1/auth':
'/v1/company/{location_id}':
```

### 3. V2 Paths (6 paths)

Remove `/api` prefix:

```yaml
# Before
'/api/v2/companies/{location_id}/activities':
'/api/v2/companies/{company_id}/tags':

# After
'/v2/companies/{location_id}/activities':
'/v2/companies/{company_id}/tags':
```

### 4. Documentation

Add versioning section to `info.description`:

```markdown
# API Versioning

The API uses URL path versioning. Currently available versions:

- **V1** (`/v1/...`) - Stable, full-featured API
- **V2** (`/v2/...`) - New endpoints with improved design

Both versions are production-ready. New features may be released
in V2 only. V1 endpoints are maintained for backward compatibility.

Base URL: `https://api.alteg.io/api`

Example requests:
- V1: `GET https://api.alteg.io/api/v1/companies`
- V2: `GET https://api.alteg.io/api/v2/companies/{id}/tags`
```

### 5. Text References

Update URL mentions in `info.description`:

- `https://api.alteg.io/api/v1` → `https://api.alteg.io/api`


## What Does NOT Change

- Files in `paths/` directory (connected via `$ref`)
- Schemas, responses, components
- operationId values
- Arazzo test files (they reference operationId, not URLs)


## Validation

```bash
make lint        # OpenAPI validation
make test-api    # Arazzo fast-check
make build-dev   # Build documentation
```

## Risks

| Risk | Mitigation |
|  --- | --- |
| Break existing spec references | Lint check after changes |
| Arazzo tests fail to find operationId | operationId unchanged |
| External systems use spec directly | Breaking change, internal docs only |