### Python SDK usage

Source: https://nflmeta.org/api-docs/analytics

Install nflmeta for Python. The example creates a client with an API key from the environment, then calls plays.leaders and plays.summary, printing the data arrays.

```python
import os
from nflmeta import NFLMetaClient

client = NFLMetaClient(api_key=os.environ["NFLMETA_API_KEY"])
leaders = client.plays.leaders(
    season=2024, season_type="REG", role="passer",
    sort="epa_per_play", min_plays=100, limit=10,
)
trends = client.plays.summary(
    season_from=2022, season_to=2024,
    season_type="REG", group_by="season",
)
print(leaders.data, trends.data)
```

--------------------------------

### TypeScript/JavaScript SDK usage

Source: https://nflmeta.org/api-docs/analytics

Install @nflmeta/sdk for server-side TypeScript/JavaScript. The example creates a client with an API key from the environment, then calls plays.leaders and plays.summary, logging the data arrays.

```typescript
import { NFLMetaClient } from "@nflmeta/sdk";

const client = new NFLMetaClient({ apiKey: process.env.NFLMETA_API_KEY });
const leaders = await client.plays.leaders({
  season: 2024, season_type: "REG", role: "passer",
  sort: "epa_per_play", min_plays: 100, limit: 10,
});
const trends = await client.plays.summary({
  season_from: 2022, season_to: 2024,
  season_type: "REG", group_by: "season",
});
console.log(leaders.data, trends.data);
```

--------------------------------

### List curated image assets: GET /api/v1/assets/images

Source: https://nflmeta.org/api-docs/reference-data

Example request and response for the GET /api/v1/assets/images endpoint. The request uses a limit query parameter of 50. The response shows a single image asset with metadata including total, limit, offset, returned, has_more, and groups.

```http
GET /api/v1/assets/images?limit=50
```

```json
{
  "data": [
    {
      "id": "brand-nflmeta-logo",
      "group": "brand",
      "key": "nflmeta_logo",
      "label": "NFLMeta Logo",
      "url": "https://nflmeta.org/hero_main/NFLMeta_Logo.png",
      "source": "local"
    }
  ],
  "meta": {
    "total": 11,
    "limit": 100,
    "offset": 0,
    "returned": 1,
    "has_more": false,
    "groups": [
      "all",
      "brand",
      "players"
    ]
  }
}
```

--------------------------------

### Install nflmeta via pip

Source: https://nflmeta.org/api-docs/sdk

Install the official Python client from PyPI for scripts, notebooks, ETL, research tools, and server-side Python applications. Requires Python 3.10 or newer.

```bash
pip install nflmeta
```

--------------------------------

### List logo assets: GET /api/v1/assets/logos

Source: https://nflmeta.org/api-docs/reference-data

Example request for the GET /api/v1/assets/logos endpoint. The request uses a limit query parameter of 50.

```http
GET /api/v1/assets/logos?limit=50
```

--------------------------------

### Get team wordmark response

Source: https://nflmeta.org/api-docs/reference-data

Example response for a single team wordmark asset. The `data` object contains the asset details without a `meta` block.

```json
{
  "data": {
    "id": "wordmark-pit",
    "kind": "wordmark",
    "key": "PIT",
    "abbr": "PIT",
    "label": "Pittsburgh Steelers",
    "team_name": "Pittsburgh Steelers",
    "url": "https://nflmeta.org/Team_Names/Pittsburgh_Steelers_Script.svg.webp",
    "source": "local"
  }
}
```

--------------------------------

### Get Coach Identity - Example Request and Response

Source: https://nflmeta.org/api-docs/core-endpoints

Request and response for the coach identity endpoint. The response includes coach_key, display_name, photo_path, hall_of_fame, and rank.

```http
GET /api/v1/coaches/mike-tomlin/identity
```

```json
{
  "data": {
    "coach_key": "mike-tomlin",
    "display_name": "Mike Tomlin",
    "photo_path": "/media/a/EXAMPLEKEY0002?v=1",
    "hall_of_fame": false,
    "rank": 12
  }
}
```

--------------------------------

### Get Coach History - Example Request and Response

Source: https://nflmeta.org/api-docs/core-endpoints

Request and response for the coach history endpoint. The response includes history, awards, team_records, and stadium_summaries arrays.

```http
GET /api/v1/coaches/mike-tomlin/history
```

```json
{
  "data": {
    "history": [
      {
        "season_year": 2025,
        "team_abbr": "PIT",
        "team_name": "Pittsburgh Steelers"
      }
    ],
    "awards": [
      {
        "award_name": "AP Coach of the Year",
        "award_count": 1,
        "first_year": 2008,
        "last_year": 2008
      }
    ],
    "team_records": [
      {
        "team_abbr": "PIT",
        "first_year": 2007,
        "last_year": 2025,
        "wins": 183,
        "losses": 107
      }
    ],
    "stadium_summaries": [
      {
        "team_abbr": "PIT",
        "first_year": 2007,
        "last_year": 2025,
        "stadium_names": "Acrisure Stadium"
      }
    ]
  }
}
```

--------------------------------

### Install @nflmeta/sdk via npm

Source: https://nflmeta.org/api-docs/sdk

Install the official TypeScript/JavaScript SDK from npm for Node and server-side JavaScript applications. The package is MIT-licensed and ships its own type declarations, so no separate @types package is needed.

```bash
npm install @nflmeta/sdk
```

--------------------------------

### Find a staff key with GET /api/v1/staff?search=cignetti

Source: https://nflmeta.org/api-docs/identifiers

Call the staff list endpoint with a search query to get the canonical staff_key. Use the returned staff_key with /api/v1/staff/{staff_key} and staff subroutes.

```http
GET /api/v1/staff?search=cignetti
```

--------------------------------

### GET /api/v1/show

Source: https://nflmeta.org/api-docs/search

Returns lightweight product capability checks and public demo surfaces.

```APIDOC
## GET /api/v1/show

### Description
Returns lightweight product capability checks and public demo surfaces.

### Method
GET

### Endpoint
/api/v1/show

### Response
#### Success Response (200)
- **capabilities** (object) - Product capability information.
- **demo** (object) - Public demo surfaces.

#### Response Example
```json
{
  "capabilities": {},
  "demo": {}
}
```
```

--------------------------------

### Get Coach Career Field - Example Request and Response

Source: https://nflmeta.org/api-docs/core-endpoints

Request and response for the coach career field endpoint. The response contains the requested field name and its value.

```http
GET /api/v1/coaches/mike-tomlin/career/regular_wins
```

```json
{
  "data": {
    "field": "regular_wins",
    "value": 183
  }
}
```

--------------------------------

### Find a venue key with GET /api/v1/reference/venues?q=arrowhead

Source: https://nflmeta.org/api-docs/identifiers

Call the raw venue reference list to get a canonical venue_key for a stadium or historical venue. Use the returned venue_key with /api/v1/reference/venues/{venue_key}.

```http
GET /api/v1/reference/venues?q=arrowhead
```

--------------------------------

### GET /api/v1/stats/players/compare

Source: https://nflmeta.org/api-docs

Compares player stats.

```APIDOC
## GET /api/v1/stats/players/compare

### Description
Compares player stats.

### Method
GET

### Endpoint
/api/v1/stats/players/compare
```

--------------------------------

### Get one game's play sequence with curl

Source: https://nflmeta.org/api-docs/recipes

Use a game id as the narrowing filter to get the snaps themselves. The API refuses requests without a narrowing filter. Add skip_markers=true to drop clock and administrative rows.

```bash
curl -H 'X-NFLMeta-Key: YOUR_KEY' 'https://nflmeta.org/api/v1/plays?game_id=21390&skip_markers=true&limit=5'
```

--------------------------------

### GET /api/v1/games/{id}/extras

Source: https://nflmeta.org/api-docs/search

Gets regular game extras. Rich game detail pages that need joined metadata without chaining many requests.

```APIDOC
## GET /api/v1/games/{id}/extras

### Description
Gets regular game extras. Rich game detail pages that need joined metadata without chaining many requests.

### Method
GET

### Endpoint
/api/v1/games/{id}/extras

### Parameters
#### Path Parameters
- **id** (string) - Required - Game id.
```

--------------------------------

### GET /api/v1/coaches/{coach_key}

Source: https://nflmeta.org/api-docs/search

Returns the main coach object for a single person.

```APIDOC
## GET /api/v1/coaches/{coach_key}

### Description
Returns the main coach object for a single person.

### Method
GET

### Endpoint
/api/v1/coaches/{coach_key}

### Parameters
#### Path Parameters
- **coach_key** (string) - Required - Coach key (e.g., mike-vrabel).

### Request Example
curl -H 'X-NFLMeta-Key: YOUR_KEY' https://nflmeta.org/api/v1/coaches/mike-vrabel
```

--------------------------------

### GET /api/v1/usage

Source: https://nflmeta.org/api-docs/quickstart

Retrieves current usage and quota information for the authenticated API key.

```APIDOC
## GET /api/v1/usage

### Description
Check current usage and quota for the authenticated API key. Confirms auth, quota headers, and live key wiring.

### Method
GET

### Endpoint
https://nflmeta.org/api/v1/usage

### Parameters
#### Headers
- **X-NFLMeta-Key** (string) - Required - Your API key.

### Request Example
```
curl -H 'X-NFLMeta-Key: YOUR_KEY' https://nflmeta.org/api/v1/usage
```

### Response
#### Success Response (200)
- **data** (object) - Usage and quota details.
  - **api_key_id** (integer) - The API key ID.
  - **billing_plan** (string) - The billing plan (e.g., "free").
  - **quota_source** (string) - Source of the quota (e.g., "plan").
  - **request_count** (integer) - Number of requests used in the current period.
  - **quota_limit** (integer) - Total request quota.
  - **quota_remaining** (integer) - Remaining request quota.
  - **request_usage_percent** (integer) - Percentage of request quota used.
  - **request_warning_level** (string) - Warning level (e.g., "none").
  - **row_count** (integer) - Number of rows used.
  - **row_quota_limit** (integer) - Total row quota.
  - **row_quota_remaining** (integer) - Remaining row quota.
  - **row_usage_percent** (integer) - Percentage of row quota used.
  - **row_warning_level** (string) - Warning level (e.g., "none").
  - **usage_guidance_url** (string) - URL for handling 429 responses.
  - **upgrade_url** (string) - URL for upgrading plan.
  - **quota_reset_at** (string) - Timestamp when quota resets.
  - **policy** (string) - Quota policy (e.g., "monthly").
  - **minute_limit** (integer) - Per-minute request limit.
  - **minute_remaining** (integer) - Remaining per-minute requests.
  - **minute_reset_at** (string) - Timestamp when minute quota resets.
  - **minute_policy** (string) - Minute policy (e.g., "per_minute").
  - **lifetime_request_count** (integer) - Total requests made since account creation.

#### Response Example
```
{
  "data": {
    "api_key_id": 42,
    "billing_plan": "free",
    "quota_source": "plan",
    "request_count": 12,
    "quota_limit": 5000,
    "quota_remaining": 4988,
    "request_usage_percent": 0,
    "request_warning_level": "none",
    "row_count": 37,
    "row_quota_limit": 25000,
    "row_quota_remaining": 24963,
    "row_usage_percent": 0,
    "row_warning_level": "none",
    "usage_guidance_url": "https://nflmeta.org/api-docs/authentication#handling-429-responses",
    "upgrade_url": "https://nflmeta.org/pricing",
    "quota_reset_at": "2026-10-01T00:00:00.000Z",
    "policy": "monthly",
    "minute_limit": 20,
    "minute_remaining": 19,
    "minute_reset_at": "2026-09-08T01:02:00.000Z",
    "minute_policy": "per_minute",
    "lifetime_request_count": 12
  }
}
```
```

--------------------------------

### GET /api/v1/reference/venues

Source: https://nflmeta.org/api-docs/search

Returns a raw venue reference list. Use the returned venue_key with /api/v1/reference/venues/{venue_key}.

```APIDOC
## GET /api/v1/reference/venues

### Description
Returns a raw venue reference list. Use the returned venue_key with /api/v1/reference/venues/{venue_key}.

### Method
GET

### Endpoint
/api/v1/reference/venues

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query for a venue.

### Response
#### Success Response (200)
- **venue_key** (string) - Canonical venue key to use with /api/v1/reference/venues/{venue_key}.
```

--------------------------------

### GET /api/v1/staff/{staff_key}

Source: https://nflmeta.org/api-docs/search

Returns the current assistant, coordinator, or support-staff profile for one person.

```APIDOC
## GET /api/v1/staff/{staff_key}

### Description
Returns the current assistant, coordinator, or support-staff profile for one person.

### Method
GET

### Endpoint
/api/v1/staff/{staff_key}

### Parameters
#### Path Parameters
- **staff_key** (string) - Required - Staff key (e.g., frank-cignetti-jr).

### Request Example
curl -H 'X-NFLMeta-Key: YOUR_KEY' https://nflmeta.org/api/v1/staff/frank-cignetti-jr
```

--------------------------------

### GET /api/v1/players/{player_key}/games

Source: https://nflmeta.org/api-docs/search

Returns game-by-game stat lines for one player.

```APIDOC
## GET /api/v1/players/{player_key}/games

### Description
Returns game-by-game stat lines for one player. Use season and week filters for granular lookups.

### Method
GET

### Endpoint
/api/v1/players/{player_key}/games

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The unique identifier for the player.

#### Query Parameters
- **season** (integer) - Optional - The season year.
- **week** (integer) - Optional - The week number.

### Response
#### Success Response (200)
- **games** (array) - List of game stat lines.

#### Response Example
```json
{
  "games": []
}
```
```

--------------------------------

### GET /api/v1/games/{id}/weather

Source: https://nflmeta.org/api-docs/search

Retrieves game-day weather forecast for the venue and kickoff time.

```APIDOC
## GET /api/v1/games/{id}/weather

### Description
Returns the forecast for the game's venue and kickoff. Within the hourly forecast window, forecast.kickoff contains conditions nearest kickoff and forecast.game_window covers the expected game. Farther out, the response provides a daily outlook without presenting it as an exact kickoff forecast. Fixed-roof venues are identified because outside weather does not describe field conditions; retractable-roof venues retain an explicit unknown until a roof decision is available. Forecasts are cached for six hours while kickoff is farther away, then for ten minutes from two hours before kickoff through five hours after. Regular-season ids take precedence if the same numeric id also exists in the playoff table.

### Method
GET

### Endpoint
/api/v1/games/{id}/weather

### Parameters
#### Path Parameters
- **id** (string) - Required - The game identifier.

```

--------------------------------

### GET /api/v1/players/{player_key}

Source: https://nflmeta.org/api-docs/search

Returns the main player profile object for one player key.

```APIDOC
## GET /api/v1/players/{player_key}

### Description
Returns the main player profile object for one player key.

### Method
GET

### Endpoint
/api/v1/players/{player_key}

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The unique identifier for the player.

### Response
#### Success Response (200)
- **player** (object) - The main player profile object.

#### Response Example
```json
{
  "player": {}
}
```
```

--------------------------------

### GET /api/v1/history/stadiums

Source: https://nflmeta.org/api-docs/search

Lists stadium history timeline for historical reference browsing.

```APIDOC
## GET /api/v1/history/stadiums

### Description
Historical reference browsing for logos, officials, stadiums, or venues.

### Method
GET

### Endpoint
/api/v1/history/stadiums

```

--------------------------------

### Python Client Initialization and Usage

Source: https://nflmeta.org/api-docs/sdk

Shows how to create an NFLMetaClient in Python, configure it with an API key and timeout, and use the teams and usage resources. Includes error handling for NFLMetaNotFoundError.

```APIDOC
## Python Client

### Description
Initialize the NFLMetaClient with an API key and timeout, then use resource clients like teams and usage.

### Example
```python
from nflmeta import NFLMetaClient, NFLMetaNotFoundError

client = NFLMetaClient(
    api_key="YOUR_KEY",
    timeout=10.0,
)

try:
    team = client.teams.get("PIT", season=2025)
    usage = client.usage.get()

    print(team.data["displayName"])
    print(usage.rate_limit.remaining)
except NFLMetaNotFoundError as error:
    print(error)
```

### Parameters
- **api_key** (string) - Required - API key for authentication.
- **timeout** (number) - Optional - Timeout in seconds.

### Methods
- **client.teams.get(teamId, season=...)** - Get team information. Parameters: teamId (string) required, season (int) optional.
- **client.usage.get()** - Get usage information. Returns rate_limit.remaining.

### Errors
- **NFLMetaNotFoundError** - Thrown when a resource is not found.
```

--------------------------------

### GET /api/v1/players/{player_key}/roster

Source: https://nflmeta.org/api-docs/search

Returns only roster-history rows for one player.

```APIDOC
## GET /api/v1/players/{player_key}/roster

### Description
Returns only roster-history rows for one player.

### Method
GET

### Endpoint
/api/v1/players/{player_key}/roster

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The player key.

### Response
#### Success Response (200)
- **rows** (array) - Roster-history rows.

### Response Example
```json
{
  "rows": []
}
```
```

--------------------------------

### GET /api/v1/players/{player_key}/kicking/{season_year}

Source: https://nflmeta.org/api-docs/search

Returns one season-level kicking row for a player.

```APIDOC
## GET /api/v1/players/{player_key}/kicking/{season_year}

### Description
Returns one season-level kicking row for a player.

### Method
GET

### Endpoint
/api/v1/players/{player_key}/kicking/{season_year}

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The player key.
- **season_year** (integer) - Required - The season year.

### Response
#### Success Response (200)
- **row** (object) - The season-level kicking row.

### Response Example
```json
{
  "row": {}
}
```
```

--------------------------------

### Python SDK client example

Source: https://nflmeta.org/api-docs/sdk

Use the Python SDK for scripts, notebooks, internal tools, and research workflows that want a thin synchronous client with the same resource model. Server-side only.

```python
from nflmeta import NFLMetaClient, NFLMetaNotFoundError

client = NFLMetaClient(
    api_key="YOUR_KEY",
    timeout=10.0,
)

try:
    team = client.teams.get("PIT", season=2025)
    usage = client.usage.get()

    print(team.data["displayName"])
    print(usage.rate_limit.remaining)
except NFLMetaNotFoundError as error:
    print(error)
```

--------------------------------

### GET /api/v1/executives/{executive_key}/career

Source: https://nflmeta.org/api-docs/search

Returns the executive career slice. General career lookups and app-facing reads.

```APIDOC
## GET /api/v1/executives/{executive_key}/career

### Description
Returns the executive career slice. General career lookups and app-facing reads.

### Method
GET

### Endpoint
/api/v1/executives/{executive_key}/career

### Parameters
#### Path Parameters
- **executive_key** (string) - Required - Executive key.
```

--------------------------------

### Get Coach History Field - Example Request and Response

Source: https://nflmeta.org/api-docs/core-endpoints

Request and response for the coach history field endpoint. The response contains the requested field name and its value.

```http
GET /api/v1/coaches/mike-tomlin/history/team_records
```

```json
{
  "data": {
    "field": "team_records",
    "value": [
      {
        "team_abbr": "PIT",
        "first_year": 2007,
        "last_year": 2025,
        "wins": 183,
        "losses": 107
      }
    ]
  }
}
```

--------------------------------

### First Successful Request in Python (server-side)

Source: https://nflmeta.org/api-docs/quickstart

Use this Python example to make a server-side request to the NFLMeta API. Replace YOUR_KEY with your actual API key. The response is printed as JSON.

```python
import requests

res = requests.get(
    "https://nflmeta.org/api/v1/teams/NE",
    headers={"X-NFLMeta-Key": "YOUR_KEY"},
)
print(res.json())
```

--------------------------------

### GET /api/v1/players/{player_key}/punting/{season_year}

Source: https://nflmeta.org/api-docs/search

Returns one season-level punting row for a player.

```APIDOC
## GET /api/v1/players/{player_key}/punting/{season_year}

### Description
Returns one season-level punting row for a player.

### Method
GET

### Endpoint
/api/v1/players/{player_key}/punting/{season_year}

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The player key.
- **season_year** (integer) - Required - The season year.

### Response
#### Success Response (200)
- **row** (object) - The season-level punting row.

### Response Example
```json
{
  "row": {}
}
```
```

--------------------------------

### TypeScript Client Initialization and Usage

Source: https://nflmeta.org/api-docs/sdk

Shows how to create an NFLMetaClient in TypeScript, configure it with an API key and timeout, and use the teams and usage resources. Includes error handling for NFLMetaNotFoundError.

```APIDOC
## TypeScript Client

### Description
Initialize the NFLMetaClient with an API key and timeout, then use resource clients like teams and usage.

### Example
```typescript
import { NFLMetaClient, NFLMetaNotFoundError } from "@nflmeta/sdk";

const client = new NFLMetaClient({
  apiKey: process.env.NFLMETA_API_KEY,
  timeoutMs: 10_000,
});

try {
  const team = await client.teams.get("PIT", { season: 2025 });
  const usage = await client.usage.get();

  console.log(team.data.displayName);
  console.log(usage.rateLimit.remaining);
} catch (error) {
  if (error instanceof NFLMetaNotFoundError) {
    console.error(error.message);
  }
}
```

### Parameters
- **apiKey** (string) - Required - API key for authentication.
- **timeoutMs** (number) - Optional - Timeout in milliseconds.

### Methods
- **client.teams.get(teamId, options)** - Get team information. Parameters: teamId (string) required, options.season (number) optional.
- **client.usage.get()** - Get usage information. Returns rateLimit.remaining.

### Errors
- **NFLMetaNotFoundError** - Thrown when a resource is not found.
```

--------------------------------

### GET /api/v1/reference/officials

Source: https://nflmeta.org/api-docs/search

Returns a raw officials reference list. Use the returned official_key with /api/v1/reference/officials/{official_key}.

```APIDOC
## GET /api/v1/reference/officials

### Description
Returns a raw officials reference list. Use the returned official_key with /api/v1/reference/officials/{official_key}.

### Method
GET

### Endpoint
/api/v1/reference/officials

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query for an official.

### Response
#### Success Response (200)
- **official_key** (string) - Canonical official key to use with /api/v1/reference/officials/{official_key}.
```

--------------------------------

### MCP tool call for summarize_play_efficiency

Source: https://nflmeta.org/api-docs/analytics

Example MCP tool call to summarize play efficiency trends. Requires a paid plan and an approved client. The arguments match the SDK filters.

```json
{
  "tool": "summarize_play_efficiency",
  "arguments": {
    "season_from": 2022,
    "season_to": 2024,
    "season_type": "REG",
    "group_by": "season"
  }
}
```

--------------------------------

### GET /api/v1/players/{player_key}/history

Source: https://nflmeta.org/api-docs/search

Returns historical team, season, and roster context for one player.

```APIDOC
## GET /api/v1/players/{player_key}/history

### Description
Returns historical team, season, and roster context for one player.

### Method
GET

### Endpoint
/api/v1/players/{player_key}/history

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The unique identifier for the player.

### Response
#### Success Response (200)
- **history** (object) - Historical context data.

#### Response Example
```json
{
  "history": {}
}
```
```

--------------------------------

### GET /api/v1/executives/{executive_key}/career

Source: https://nflmeta.org/api-docs/search

Returns tenure and role context for an executive without the full profile payload.

```APIDOC
## GET /api/v1/executives/{executive_key}/career

### Description
Returns tenure and role context for an executive without the full profile payload.

### Method
GET

### Endpoint
/api/v1/executives/{executive_key}/career

### Parameters
#### Path Parameters
- **executive_key** (string) - Required - Executive key (e.g., robert-kraft).

### Request Example
curl -H 'X-NFLMeta-Key: YOUR_KEY' https://nflmeta.org/api/v1/executives/robert-kraft/career
```

--------------------------------

### GET /api/v1/seasons

Source: https://nflmeta.org/api-docs/search

Returns the season catalog. Use the returned year with /api/v1/season/{year} and season subroutes.

```APIDOC
## GET /api/v1/seasons

### Description
Returns the season catalog. Use the returned year with /api/v1/season/{year} and season subroutes.

### Method
GET

### Endpoint
/api/v1/seasons

### Response
#### Success Response (200)
- **year** (integer) - Season year to use with /api/v1/season/{year} and season subroutes.
```

--------------------------------

### GET /api/v1/assets/team-logos/{abbr}

Source: https://nflmeta.org/api-docs/reference-data

Get one team logo asset. This endpoint is used for direct asset discovery for logos or image catalogs.

```APIDOC
## GET /api/v1/assets/team-logos/{abbr}

### Description
Get one team logo asset. This endpoint is used for direct asset discovery for logos or image catalogs.

### Method
GET

### Endpoint
/api/v1/assets/team-logos/{abbr}

### Parameters
#### Path Parameters
- **abbr** (string) - Required - Team abbreviation such as PIT, DAL, or SF.

#### Query Parameters
- **season** (integer) - Optional - Not provided
- **team_name** (string) - Optional - Not provided

### Request Example
```
GET /api/v1/assets/team-logos/PIT?season=2025
```

### Response
#### Success Response (200)
- **data** (object) - The team logo asset.

#### Response Example
```
{
  "data": {
    "id": "logo-pit",
    "kind": "logo",
    "key": "PIT",
    "abbr": "PIT",
    "label": "Pittsburgh Steelers",
    "team_name": "Pittsburgh Steelers",
    "url": "https://nflmeta.org/hero_main/logos/pittsburgh-steelers-logo-transparent.png",
    "source": "local"
  }
}
```
```

--------------------------------

### Start with one team object: /api/v1/teams/NE

Source: https://nflmeta.org/api-docs

Best first request to confirm authentication, inspect the response shape, and understand the slice-and-field model.

```http
/api/v1/teams/NE
```

--------------------------------

### GET /api/v1/games?season=2024&team=BAL

Source: https://nflmeta.org/api-docs/identifiers

Gets a game id to use as a filter for plays. The returned id can be used with /api/v1/plays?game_id={id}.

```APIDOC
## GET /api/v1/games?season=2024&team=BAL

### Description
Gets a game id to use as a filter for plays. The returned id can be used with /api/v1/plays?game_id={id}.

### Method
GET

### Endpoint
/api/v1/games?season=2024&team=BAL

### Parameters
#### Query Parameters
- **season** (integer) - Required - The season year.
- **team** (string) - Required - The team abbreviation.

### Response
#### Success Response (200)
- **id** (string) - The game identifier to use in plays endpoint.

#### Response Example
{
  "id": "2024_BAL_..."
}
```

--------------------------------

### List team wordmarks with limit

Source: https://nflmeta.org/api-docs/reference-data

Lists team wordmark assets. The `limit` query parameter is optional and clamped to the plan maximum; the example requests 50 rows.

```http
GET /api/v1/assets/team-wordmarks?limit=50
```

--------------------------------

### GET /api/v1/games?season=2024&team=PIT

Source: https://nflmeta.org/api-docs/identifiers

Get a list of games for a season and team to obtain the game id. Use the returned id in single-game routes.

```APIDOC
## GET /api/v1/games?season=2024&team=PIT

### Description
Get a list of games for a season and team to obtain the game id. Use the returned id in single-game routes.

### Method
GET

### Endpoint
/api/v1/games?season=2024&team=PIT

### Parameters
#### Query Parameters
- **season** (integer) - Required - Season year.
- **team** (string) - Required - Team abbreviation.

### Response
#### Success Response (200)
- **id** (string) - Game identifier.

#### Response Example
{
  "id": "2024PIT_BAL"
}
```

--------------------------------

### Check current usage and quota with curl

Source: https://nflmeta.org/api-docs/quickstart

Use this request after signup to confirm authentication, quota headers, and live key wiring. The response includes request and row usage, quota limits, warning levels, and reset times. Warning levels change at 80%, 90%, and 100%.

```bash
curl -H 'X-NFLMeta-Key: YOUR_KEY' https://nflmeta.org/api/v1/usage
```

```json
{
  "data": {
    "api_key_id": 42,
    "billing_plan": "free",
    "quota_source": "plan",
    "request_count": 12,
    "quota_limit": 5000,
    "quota_remaining": 4988,
    "request_usage_percent": 0,
    "request_warning_level": "none",
    "row_count": 37,
    "row_quota_limit": 25000,
    "row_quota_remaining": 24963,
    "row_usage_percent": 0,
    "row_warning_level": "none",
    "usage_guidance_url": "https://nflmeta.org/api-docs/authentication#handling-429-responses",
    "upgrade_url": "https://nflmeta.org/pricing",
    "quota_reset_at": "2026-10-01T00:00:00.000Z",
    "policy": "monthly",
    "minute_limit": 20,
    "minute_remaining": 19,
    "minute_reset_at": "2026-09-08T01:02:00.000Z",
    "minute_policy": "per_minute",
    "lifetime_request_count": 12
  }
}
```

--------------------------------

### GET /api/v1/executives/{executive_key}/identity

Source: https://nflmeta.org/api-docs/search

Returns the executive identity slice. General identity lookups and app-facing reads.

```APIDOC
## GET /api/v1/executives/{executive_key}/identity

### Description
Returns the executive identity slice. General identity lookups and app-facing reads.

### Method
GET

### Endpoint
/api/v1/executives/{executive_key}/identity

### Parameters
#### Path Parameters
- **executive_key** (string) - Required - Executive key.
```

--------------------------------

### MCP tool call for get_play_efficiency_leaders

Source: https://nflmeta.org/api-docs/analytics

Example MCP tool call to retrieve play efficiency leaders. Requires a paid plan and an approved client. The arguments match the SDK filters.

```json
{
  "tool": "get_play_efficiency_leaders",
  "arguments": {
    "season": 2024,
    "season_type": "REG",
    "role": "passer",
    "sort": "epa_per_play",
    "min_plays": 100,
    "limit": 10
  }
}
```

--------------------------------

### Get one raw venue record with curl

Source: https://nflmeta.org/api-docs/recipes

Use reference endpoints to get a raw venue record that stays close to the underlying table shape.

```bash
curl -H 'X-NFLMeta-Key: YOUR_KEY' https://nflmeta.org/api/v1/reference/venues/geha-field-at-arrowhead-stadium
```

--------------------------------

### GET /api/v1/players/{player_key}/history/{field}

Source: https://nflmeta.org/api-docs/search

Returns one top-level field from the player history slice.

```APIDOC
## GET /api/v1/players/{player_key}/history/{field}

### Description
Returns one top-level field from the player history slice.

### Method
GET

### Endpoint
/api/v1/players/{player_key}/history/{field}

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The unique identifier for the player.
- **field** (string) - Required - The history field to retrieve.

### Response
#### Success Response (200)
- **value** (any) - The value of the requested field.

#### Response Example
```json
{
  "value": null
}
```
```

--------------------------------

### GET /api/v1/executives/{executive_key}/bio

Source: https://nflmeta.org/api-docs/search

Returns the executive bio slice. General bio lookups and app-facing reads.

```APIDOC
## GET /api/v1/executives/{executive_key}/bio

### Description
Returns the executive bio slice. General bio lookups and app-facing reads.

### Method
GET

### Endpoint
/api/v1/executives/{executive_key}/bio

### Parameters
#### Path Parameters
- **executive_key** (string) - Required - Executive key.
```

--------------------------------

### GET /api/v1/players/{player_key}/identity/{field}

Source: https://nflmeta.org/api-docs/search

Returns a single field from the player identity slice.

```APIDOC
## GET /api/v1/players/{player_key}/identity/{field}

### Description
Returns a single field from the player identity slice. Supported fields include player_key, display_name, football_name, first_name, last_name, position_group, position, latest_team_abbr, jersey_number, rookie_season, last_season, status, roster_status, retired_at, years_of_experience, and headshot_url. Read roster_status rather than status: status is the unrevised import field and still reads Active for a player who has retired, while roster_status is derived from current roster membership.

### Method
GET

### Endpoint
/api/v1/players/{player_key}/identity/{field}

### Parameters
#### Path Parameters
- **player_key** (string) - Required - The unique identifier for the player.
- **field** (string) - Required - The identity field to retrieve.

### Response
#### Success Response (200)
- **value** (any) - The value of the requested field.

#### Response Example
```json
{
  "value": null
}
```
```