Sign In
Knowledge Base

API FAQ

Everything builders need to evaluate, integrate, and run NFLMeta in real projects.

Who This Is For

Who is NFLMeta built for?

NFLMeta is built for hobbyists, independent developers, researchers, newsletter writers, small media projects, and small businesses that want clean historical NFL data without enterprise contracts.

What kinds of projects are a good fit?

  • Fan sites, stat explorers, and football research tools
  • Developer projects, side projects, and internal dashboards
  • Newsletters, podcasts, and small content businesses
  • Apps that need structured historical games, seasons, standings, playoffs, and metadata

What is NFLMeta not trying to be?

NFLMeta is not positioned as an enterprise live-data vendor for sportsbooks or major broadcast partners. The focus is historical depth, clean structure, and practical developer access.

Getting Started

How do I get started with NFLMeta?

  1. Create an account at /register.
  2. Verify your sign-in and open Customer Portal to get your free API key.
  3. Review onboarding and auth details at /api-docs, then call endpoints under /api/v1.

What is the API base path?

Use versioned endpoints under /api/v1/*. The schema contract is published at /openapi.yaml.

What data is included?

Coverage includes games, seasons, standings, playoffs, Super Bowls, players, team history, stadium and venue history, coaches, officials, branding history, season summaries, broadcast rights, power rankings, and Pro Bowl or all-star datasets. You can browse the full surface in API Docs.

Authentication and Keys

Do I need an account before using API keys?

Yes. Sign in to create your account, and NFLMeta will automatically create one free API key after your first verified login.

How can I sign in?

Right now the hosted auth flow supports email-based sign-in and Google sign-in.

How do I authenticate requests?

Pass your key in request headers: X-NFLMeta-Key: <YOUR_KEY>.

What are key security best practices?

  • Store API keys server-side only.
  • Never ship keys in browser/mobile client bundles.
  • Rotate or replace keys when team access changes.

What happens if a key is invalid or inactive?

The API returns 401 unauthorized with a structured error payload.

Plans, Billing, and Limits

Do you offer multiple plans?

Yes. Plans range from Free to Team. See Pricing for tier details.

How do request limits work?

Limits work on two layers: a monthly quota that resets at the start of each UTC month, and a per-minute rate limit that prevents burst abuse. Both are plan-based.

Which headers show quota status?

Responses include per-minute headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Policy. Monthly quota headers are also returned: X-Monthly-Quota-Limit, X-Monthly-Quota-Remaining, X-Monthly-Quota-Reset, and X-Monthly-Quota-Policy.

What are the current per-minute limits by plan?

  • Free: 20 requests per minute
  • Builder: 120 requests per minute
  • Pro: 500 requests per minute
  • Team: 1,500 requests per minute

What happens when I exceed the rate limit or monthly quota?

The API returns 429 rate_limit_exceeded when a key exceeds either the per-minute rate limit or the monthly quota. Free keys stop at quota. Paid plans are intended to support overages based on the pricing page, but automated billing enforcement is not fully wired yet, so contact support if you expect sustained overage usage.

Can I upgrade or change plan later?

Yes. You can change plans from Customer Portal without changing how your app integrates with the API.

Can I delete my account?

Yes. Signed-in users can delete their account from Customer Portal. Deletion disables the active API key and removes the associated Clerk account.

Integration and Endpoints

Do you provide OpenAPI/SDK-friendly documentation?

Yes. The canonical spec is available at /openapi.yaml and rendered at /api-docs.

Can clients query every field in the database?

Public data coverage is broad and now includes both curated endpoints and raw table-shaped exports across players, teams, seasons, games, playoffs, coaches, officials, venues, stadiums, branding history, and Pro Bowl data. Internal operational tables like auth, billing, registrations, and refresh-state tables are not public.

How is API versioning handled?

Stable routes are versioned under /api/v1. New capabilities are added without breaking the existing version contract.

Do list endpoints support pagination/filtering?

Yes. Primary collection endpoints support query filters and paging controls where applicable. Confirm available parameters in API Docs.

Do I need to use legacy namespaces?

No. New integrations should use the current versioned API under /api/v1/*.

What is the difference between raw and curated endpoints?

Curated endpoints return joined, app-ready payloads for common product use cases. Raw endpoints return table-shaped exports that stay closer to the underlying database. API Docs labels these explicitly so you can choose the right surface quickly.

What are the reference endpoints for?

Endpoints under /api/v1/reference/* are the fastest way to pull raw rows for teams, seasons, coaches, officials, venues, stadiums, branding history, season records, power rankings, and Pro Bowl data. They are best for research, exports, and internal ETL workflows.

Where do I get raw game or playoff stat tables?

Use /api/v1/games/{id}/stats for the raw stat tables for one regular-season game and /api/v1/playoff-games/{id}/supplemental for field-complete playoff sub-tables. Use the corresponding /extras endpoints when you want lighter, joined payloads instead.

Do you expose player history and player-level raw records?

Yes. Use /api/v1/players and /api/v1/players/{player_key} for player records,/api/v1/players/{player_key}/history for player history tables like roster and honors coverage, and /api/v1/players/{player_key}/games for granular game logs such as passing yards, touchdowns, and interceptions by week.

Operations and Support

What usage patterns do you recommend?

  • Use server-side caching for frequently requested resources.
  • Implement retry with backoff for transient failures.
  • Monitor your quota headers and endpoint-level usage.

Do you have a trust/security overview page?

Yes. Visit Trust Center for security, reliability, and governance posture.