# Sportsmarks Developer API

> Programmatic access to official logos, colors, trademarked verbiage, and brand
> guidelines for collegiate and professional sports teams. Built for AI agents,
> automation, and integrations.

- **Base URL**: `https://sportsmarks.com/api/v1`
- **Format**: JSON. Success responses wrap data in a `data` object; errors return
  `{ "error": "...", "message": "..." }`.
- **Auth**: Bearer token (API key) in the `Authorization` header.
- **Get a key**: sign in at https://sportsmarks.com/developers and click
  "Create API Key". Keys look like `sm_live_<32 chars>` and are shown once.

## Quickstart

```bash
curl -s "https://sportsmarks.com/api/v1/institutions?search=utah" \
  -H "Authorization: Bearer sm_live_your_api_key"
```

## Authentication

All endpoints require this header:

```
Authorization: Bearer sm_live_your_api_key
```

Missing/invalid/expired keys → `401`. Server errors → `5xx`. Not found → `404`.

## Response shape

```json
{
  "data": { "...endpoint-specific payload..." }
}
```

Errors:

```json
{ "error": "Invalid or expired API key",
  "message": "Please check your API key is correct and active" }
```

## Endpoints

### `GET /institutions`

List institutions with filtering, search, sorting, and pagination.

Query parameters:

| Param | Type | Description |
|---|---|---|
| `page` | integer | Page number (default: 1) |
| `per_page` | integer | Items per page (default: 50, max: 100) |
| `league` | string | Comma-separated league names (e.g. `NCAA,NFL`) |
| `conference` | string | Comma-separated conference names (e.g. `Big 12,SEC`) |
| `search` | string | Matches institution name, slug, conference name, or league name (case-insensitive) |
| `sort` | string | `name` (default), `-name`, `slug`, `-slug` — prefix with `-` for descending |

Response payload (`data`):

```json
{
  "institutions": [
    {
      "id": "uuid",
      "name": "University of Utah",
      "slug": "university-of-utah",
      "conference": { "id": "uuid", "name": "Big 12", "slug": "big-12" },
      "league": { "id": "uuid", "name": "NCAA", "slug": "ncaa" },
      "links": {
        "self": "https://sportsmarks.com/api/v1/institutions/university-of-utah",
        "logos": "https://sportsmarks.com/api/v1/institutions/university-of-utah/logos",
        "colors": "https://sportsmarks.com/api/v1/institutions/university-of-utah/colors",
        "verbiage": "https://sportsmarks.com/api/v1/institutions/university-of-utah/verbiage",
        "web": "https://sportsmarks.com/university-of-utah"
      }
    }
  ],
  "pagination": {
    "page": 1, "per_page": 50, "total": 281, "total_pages": 6,
    "has_next": true, "has_prev": false
  }
}
```

### `GET /institutions/{slug}`

Complete details for a single institution: bio, all logos with file URLs,
color palette, trademarked verbiage, restrictions, brand score.

Query parameters:

| Param | Type | Description |
|---|---|---|
| `file_type` | string | Subset embedded logo files. Comma-separated (e.g. `svg,png`). |
| `strict` | boolean | When used with `file_type`, drop logos that have no remaining files after filtering. |

### `GET /institutions/{slug}/logos`

Logos for a single institution.

Query parameters:

| Param | Type | Description |
|---|---|---|
| `primary_only` | boolean | Only return primary logos |
| `group` | string | Filter by logo group name |
| `file_type` | string | Filter by file type (`svg`, `png`, etc.) |

### `GET /institutions/{slug}/colors`

Colors for a single institution.

Query parameters:

| Param | Type | Description |
|---|---|---|
| `primary_only` | boolean | Only return primary colors |
| `format` | string | `full` (default) returns hex/rgb/hsl/cmyk/pantone/threads; `hex` returns minimal payload |

### `GET /institutions/{slug}/verbiage`

Trademarked phrases for a single institution.

Query parameters:

| Param | Type | Description |
|---|---|---|
| `trademark_type` | string | `none`, `trademarked`, or `registered` |

### `GET /logos`

Cross-institution logo search. Returns logos across **all** institutions with
parent institution, conference, and league attached to each.

Query parameters:

| Param | Type | Description |
|---|---|---|
| `file_type` | string | Comma-separated file types. Logos with no remaining files are dropped. |
| `primary_only` | boolean | Only return primary logos |
| `group` | string | Comma-separated group names (e.g. `Primary Marks`) |
| `league` | string | Comma-separated league names |
| `conference` | string | Comma-separated conference names |
| `institution_slug` | string | Comma-separated institution slugs |
| `page` | integer | Page number (default: 1) |
| `per_page` | integer | Items per page (default: 50, max: 100) |

Example:

```bash
curl -s "https://sportsmarks.com/api/v1/logos?file_type=svg&primary_only=true&league=NCAA&conference=Big%2012" \
  -H "Authorization: Bearer sm_live_your_api_key"
```

### `GET /leagues`

List every league. Useful for discovering valid `league=` filter values. No parameters.

### `GET /conferences`

List every conference, each with its parent league.

Query parameters:

| Param | Type | Description |
|---|---|---|
| `league` | string | Comma-separated league names |

## Code examples

### JavaScript / TypeScript

```ts
const API_KEY = process.env.SPORTSMARKS_API_KEY!;
const BASE = 'https://sportsmarks.com/api/v1';

async function get<T>(path: string): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  if (!res.ok) throw new Error(`API ${res.status}: ${await res.text()}`);
  const json = await res.json();
  return json.data as T;
}

const utah = await get<any>('/institutions/university-of-utah');
const svgs = await get<any>('/logos?file_type=svg&primary_only=true&league=NCAA');
```

### Python

```python
import os, requests
API_KEY = os.environ['SPORTSMARKS_API_KEY']
BASE = 'https://sportsmarks.com/api/v1'
H = {'Authorization': f'Bearer {API_KEY}'}

def get(path):
    r = requests.get(f'{BASE}{path}', headers=H, timeout=10)
    r.raise_for_status()
    return r.json()['data']

utah = get('/institutions/university-of-utah')
svgs = get('/logos?file_type=svg&primary_only=true&league=NCAA')
```

### cURL

```bash
KEY=sm_live_your_api_key

# Search across name, slug, conference, league
curl -s "https://sportsmarks.com/api/v1/institutions?search=big%2012" -H "Authorization: Bearer $KEY"

# Pull SVGs only, primary only, across the Big 12
curl -s "https://sportsmarks.com/api/v1/logos?file_type=svg&primary_only=true&conference=Big%2012" -H "Authorization: Bearer $KEY"

# Discover filter values
curl -s "https://sportsmarks.com/api/v1/leagues" -H "Authorization: Bearer $KEY"
curl -s "https://sportsmarks.com/api/v1/conferences?league=NCAA" -H "Authorization: Bearer $KEY"
```

## Notes for AI agents

- All endpoints are pure GET; safe to call without confirmation.
- URLs are stable. `slug` is the canonical identifier (e.g. `brigham-young-university`).
- Logo file URLs returned in responses are public CDN URLs and can be embedded
  directly. They are stable for a given logo file.
- Per-institution markdown for individual schools is available at
  `https://sportsmarks.com/{slug}/llms.txt`.
- Per-league markdown at `https://sportsmarks.com/league/{slug}/llms.txt`.
- A site-wide index lives at `https://sportsmarks.com/llms.txt`.

## Rate limits

Usage is tracked per API key. Fair-use limits may apply, and abusive traffic
patterns can result in keys being rate-limited or revoked. Contact us for
enterprise plans.

## Legal

Logos, trademarks, and brand assets exposed by this API are owned by their
respective institutions. Proper licensing is required for commercial use. The
API surfaces canonical assets and licensing metadata — it does not grant any
license itself.

- Terms: https://sportsmarks.com/terms
- Privacy: https://sportsmarks.com/privacy
- Human-readable docs: https://sportsmarks.com/developers