# RaceTagger API — Full Documentation for LLMs

> AI-powered sports & motorsport photo recognition API.
> Detect race bib numbers, sponsor logos, license plates, aircraft markings.
> Match detections to participant data for automated photo organization.
> First API built specifically for race and sports photography analysis.

## Quick Start

Base URL: https://racetagger.cloud/api/v1
Auth: Authorization: Bearer rt_live_your_key
Get a key: https://racetagger.cloud/api-access

### Analyze an image (curl)

```bash
curl -X POST https://racetagger.cloud/api/v1/analyze \
  -H "Authorization: Bearer rt_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/race-photo.jpg",
    "category": "motorsport"
  }'
```

### Analyze an image (Python)

```python
import requests

response = requests.post(
    "https://racetagger.cloud/api/v1/analyze",
    headers={"Authorization": "Bearer rt_live_your_key"},
    json={
        "image_url": "https://example.com/race-photo.jpg",
        "category": "motorsport"
    }
)

result = response.json()
for vehicle in result["detection"]["vehicles"]:
    print(f"#{vehicle['race_number']} — confidence: {vehicle['confidence']}")
```

### Analyze an image (JavaScript)

```javascript
const response = await fetch("https://racetagger.cloud/api/v1/analyze", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rt_live_your_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    image_url: "https://example.com/race-photo.jpg",
    category: "motorsport"
  })
});

const result = await response.json();
result.detection.vehicles.forEach(v => {
  console.log(`#${v.race_number} — confidence: ${v.confidence}`);
});
```

## Endpoints

### POST /api/v1/analyze (1 credit)

Analyze a single image. Detects vehicles/participants, race numbers, sponsors, and visual features.

Request body:
```json
{
  "image_url": "https://example.com/photo.jpg",
  "category": "motorsport",
  "options": {
    "enable_visual_matching": true,
    "min_confidence": 0.5
  }
}
```

Alternative: use "image_base64" instead of "image_url" for base64-encoded images.

Response:
```json
{
  "success": true,
  "analysis_id": "exec_abc123",
  "processing_time_ms": 2340,
  "detection": {
    "method": "hybrid",
    "total_vehicles": 2,
    "vehicles": [
      {
        "vehicle_index": 0,
        "position": "center",
        "race_number": "46",
        "confidence": 0.95,
        "visual_features": {
          "vehicle_colors": ["#FFD700", "#0000FF"],
          "sponsors": ["Monster Energy", "Yamaha"],
          "brand": "Yamaha"
        },
        "bounding_box": { "x": 120, "y": 80, "width": 340, "height": 260 }
      }
    ],
    "image_context": {
      "scene": "race_track",
      "lighting": "daylight",
      "quality": "high"
    }
  },
  "metadata": {
    "race_numbers": ["46"],
    "driver_names": [],
    "teams": [],
    "sponsors": ["Monster Energy", "Yamaha"],
    "category": "motogp"
  },
  "credits": {
    "consumed": 1,
    "remaining": 99
  }
}
```

### POST /api/v1/match (0 credits — FREE)

The key differentiator. Match previously detected race numbers against a participant list. Handles OCR errors, number corrections, and ambiguity resolution. Generates filenames, keywords, and descriptions.

This endpoint is FREE to encourage adoption.

Request:
```json
{
  "analysis_id": "exec_abc123",
  "participants": [
    { "number": "46", "name": "Valentino Rossi", "team": "Yamaha Factory" },
    { "number": "93", "name": "Marc Marquez", "team": "Repsol Honda" },
    { "number": "48", "name": "Lorenzo Dalla Porta", "team": "Leopard Racing" }
  ]
}
```

Response:
```json
{
  "success": true,
  "analysis_id": "exec_abc123",
  "matches": [
    {
      "detection_number": "46",
      "participant": {
        "number": "46",
        "name": "Valentino Rossi",
        "team": "Yamaha Factory",
        "category": null
      },
      "confidence": 1.0,
      "match_type": "exact"
    }
  ],
  "unmatched_detections": [],
  "suggested_filename": "motogp_46_Valentino-Rossi",
  "keywords": ["motogp", "#46", "Valentino Rossi", "Yamaha Factory", "Monster Energy"],
  "description": "motogp photo featuring Valentino Rossi (#46) at race track",
  "credits": { "consumed": 0, "remaining": 99 }
}
```

Match types:
- "exact": detected number matches participant number exactly
- "corrected": OCR error was corrected (e.g., "48" detected but "46" matched via OCR variant)
- "ambiguous": multiple possible matches, best guess returned with alternatives
- "visual": matched by visual features (colors, livery) when number not readable

### POST /api/v1/analyze-and-match (1 credit)

Combined endpoint: analyze image + match participants in one call.

Request:
```json
{
  "image_url": "https://example.com/photo.jpg",
  "category": "running",
  "participants": [
    { "number": "1234", "name": "John Doe", "team": "NYC Runners" },
    { "number": "5678", "name": "Jane Smith" }
  ]
}
```

Response combines detection + match data in a single response.

### POST /api/v1/analyze/batch (1 credit per image)

Analyze up to 50 images in parallel. Credits consumed only for successful analyses.

Request:
```json
{
  "images": [
    { "image_url": "https://example.com/photo1.jpg", "category": "motorsport" },
    { "image_url": "https://example.com/photo2.jpg", "category": "motorsport" },
    { "image_url": "https://example.com/photo3.jpg" }
  ],
  "options": { "enable_visual_matching": true }
}
```

Response includes per-image results + summary:
```json
{
  "success": true,
  "results": [ ... ],
  "summary": { "total": 3, "successful": 3, "failed": 0, "total_processing_ms": 5200 },
  "credits": { "consumed": 3, "remaining": 97 }
}
```

### GET /api/v1/results/:id (0 credits)

Retrieve a previously completed analysis result by ID.

```bash
curl https://racetagger.cloud/api/v1/results/exec_abc123 \
  -H "Authorization: Bearer rt_live_your_key"
```

### GET /api/v1/usage (0 credits)

Check credit balance and usage statistics.

```bash
curl https://racetagger.cloud/api/v1/usage \
  -H "Authorization: Bearer rt_live_your_key"
```

Response:
```json
{
  "tier": "sandbox",
  "environment": "live",
  "credits": {
    "limit": 100,
    "used": 15,
    "remaining": 85,
    "period_start": "2026-02-01T00:00:00Z",
    "period_end": "2026-03-01T00:00:00Z"
  },
  "rate_limit": { "requests_per_minute": 10 },
  "stats": {
    "total_requests": 42,
    "total_credits_consumed": 15,
    "requests_today": 3,
    "credits_today": 2,
    "avg_processing_ms": 2100,
    "top_endpoints": [
      { "endpoint": "/api/v1/analyze", "count": 30 },
      { "endpoint": "/api/v1/match", "count": 12 }
    ]
  }
}
```

## Authentication

API keys use the format: rt_live_xxx (production) or rt_test_xxx (sandbox/testing).
Pass via Authorization header: `Authorization: Bearer rt_live_your_key`

Request a key: https://racetagger.cloud/api-access
Sandbox tier: 100 free credits/month on manual approval.

## Categories

| Category | Description | Use cases |
|----------|-------------|-----------|
| motorsport | F1, MotoGP, karting, motocross, rally, enduro | Race number + sponsor detection |
| running | Marathons, trail running, cross country | Bib number detection |
| cycling | Road cycling, MTB, gran fondo | Jersey number + team detection |
| street | Street vehicles | License plate recognition |
| aviation | Aircraft | Registration, airline, model ID |

## Error Handling

All errors include machine-readable codes and suggestions for self-correction:

```json
{
  "success": false,
  "error": {
    "code": "credits_exhausted",
    "message": "No credits remaining. You have used 100 of 100 credits this period.",
    "suggestion": "Upgrade your plan at https://racetagger.cloud/dashboard or wait for the next billing period.",
    "docs_url": "https://racetagger.cloud/docs/api/errors#credits_exhausted"
  }
}
```

Error codes:
- unauthorized (401): Invalid or missing API key
- credits_exhausted (402): No credits remaining
- rate_limited (429): Too many requests, includes Retry-After header
- bad_request (400): Invalid request parameters
- image_required (400): No image provided
- result_not_found (404): Analysis ID not found

## Image Input

Three ways to provide images:
1. image_url — HTTPS URL to an image (JPEG, PNG, WebP)
2. image_base64 — Base64-encoded image data (with or without data: prefix)
3. Batch — Array of images (up to 50) via /analyze/batch

Recommended: < 4MB per image for optimal speed.

## MCP Server (for AI Agents)

RaceTagger provides a Model Context Protocol (MCP) server for direct AI agent integration.

Remote endpoint: https://racetagger.cloud/mcp
Discovery: https://racetagger.cloud/.well-known/mcp.json
Compatible with: Claude Desktop, Cursor, Windsurf, and any MCP client.

Available tools:
- racetagger_analyze: Analyze a single image
- racetagger_match: Match detections to participants
- racetagger_search: Search analysis history
- racetagger_export: Export results
- racetagger_usage: Check credits and usage

## Pricing

| Tier | Price | Credits/month | Rate limit |
|------|-------|---------------|------------|
| Sandbox | Free | 100 | 10/min |
| Starter | EUR 19/mo | 2,000 | 60/min |
| Pro | EUR 49/mo | 8,000 | 120/min |
| Business | EUR 99/mo | 20,000 | 200/min |
| Enterprise | Custom | Custom | 500/min |

Match endpoint (/api/v1/match) is always free, 0 credits.

## OpenAPI Specification

Full machine-readable spec: https://racetagger.cloud/docs/api/openapi.yaml

## Company

- Website: https://racetagger.cloud
- API Access: https://racetagger.cloud/api-access
- Support: info@racetagger.cloud
- Status: https://status.racetagger.cloud