Reference
External API
Understand the customer-safe HotRoute external API surface for approved service-account access.
Overview / Purpose
The HotRoute external API lets an approved integration ask for specific HotRoute information through organization-owned service-account access.
It is not a broad data export, a staff login, or a shortcut around team, season, role, plan, lifecycle, or privacy boundaries.
Use this page to understand which resource families are visible at a customer-safe level and how denied responses should be interpreted.
Who this is for
This reference is for organization owners, football operations leads, analysts, and approved technical partners.
In football terms, this is for the person deciding whether a trusted outside tool should read limited team context, render a callsheet, search visible terminology, or retrieve scoped playbook information.
What to know first
External API access starts with a service account. The organization owner creates the account, chooses the team and season scope, selects object families, selects operation classes, and stores the key securely.
An API key does not become a coach's personal login. It represents the organization-owned integration and only works inside the scope the owner granted.
Most private football resources need clear organization, team, season, playbook, or object context. If that context is missing, ambiguous, out of scope, unavailable on the plan, or unsafe to reveal, HotRoute should refuse or return a safe not-found style response.
Some routes require an idempotency key, version check, or bounded request shape before HotRoute accepts expensive or write-like work. That keeps retries, imports, renders, and updates from creating unclear downstream state.
Published endpoint inventory
This inventory is conclusive for the current /api/v1 service-account surface. If a route is not listed here, treat it as unavailable for customer API-key use unless HotRoute explicitly approves a later customer route.
For paths with {id}, use the HotRoute id returned by a visible prior response. A returned id is still usable only inside the organization, team, season, object family, operation, plan, lifecycle, and role boundaries granted to the service account.
Status language on this page is intentional:
- Beta-live means the route family is available for approved service-account API use when the key, scope, plan, lifecycle, and request checks pass.
- Private-preview means HotRoute must approve the exact customer workflow before use.
- Planned means the route family or tool workflow is not available for general service-account use yet.
- Unavailable means the operation is not a customer API-key route.
Route-family availability
| Route family | Status | Customer-safe boundary |
|---|---|---|
| Core team, season, playbook, play, terminology, opponent, and schedule metadata | Beta-live | Read routes return bounded metadata only. |
| Registry-backed read projections | Beta-live | The generic projection routes listed below are read-only and field-allowlisted. |
| Schedule create, update, and import preview | Beta-live | Writes are bounded to active schedule events and non-committing import previews. |
| Callsheet render and callsheet layout drafts | Beta-live | Rendered artifacts and layout drafts are derived from visible playbook context. |
| Private semantic search | Beta-live | Requires the semantic-search add-on or grant, explicit team and season scope, citations, and rate-limit checks. |
| Product-doc semantic context | Beta-live | Searches HotRoute product docs only; it does not expose customer-private football truth. |
Customer agent workflows with Codex, Claude, ChatGPT, MCP, or hotroute-tools | Private-preview or planned | Use only after HotRoute and the organization owner approve the exact scoped workflow. |
| User-delegated OAuth agent access | Planned | Service-account keys must not be treated as individual coach consent. |
| Review, publish, archive, billing admin, support admin, platform admin, and unlisted mutations | Unavailable | These are not customer API-key operations. |
Core endpoints
| Endpoint | Operation | Customer-safe result |
|---|---|---|
GET /api/v1/teams | List teams | Active in-scope team summaries. |
GET /api/v1/teams/{teamId} | Retrieve team | One in-scope team summary. |
GET /api/v1/seasons | List seasons | In-scope season summaries and current-season context. |
GET /api/v1/seasons/{seasonId} | Retrieve season | One in-scope season summary. |
GET /api/v1/playbooks | List playbooks | Active playbook summaries in the requested scope. |
GET /api/v1/playbooks/{playbookId} | Retrieve playbook | One active playbook summary. |
GET /api/v1/plays | List plays | Published play metadata from active scoped playbooks. |
GET /api/v1/plays/{playId} | Retrieve play | One published play metadata response. |
GET /api/v1/terminology | List terms | Published baseline and visible organization terminology. |
GET /api/v1/terminology/search | Search terms | Bounded terminology search results. |
GET /api/v1/terminology/{termId} | Retrieve term | One visible published term with safe aliases and usage context. |
GET /api/v1/opponents | List opponents | Active opponent identity metadata tied to same-team, same-season schedule context. |
GET /api/v1/opponents/{opponentId} | Retrieve opponent | One active opponent identity response. |
GET /api/v1/schedule | List schedule events | Active same-team, same-season schedule events. |
GET /api/v1/schedule/{scheduleEventId} | Retrieve schedule event | One active schedule event. |
POST /api/v1/schedule/import-preview | Preview schedule import | Non-committing preview results for at most the approved bounded import payload. |
POST /api/v1/schedule | Create schedule event | Creates one active schedule event with bounded fields. |
PUT /api/v1/schedule/{scheduleEventId} | Update schedule event | Updates one active schedule event when version checks pass. |
POST /api/v1/callsheets/render | Render callsheet artifact | Derived output from visible playbook context. |
GET /api/v1/callsheet-layouts | List callsheet layouts | Published callsheet layout roots visible to the service account. |
GET /api/v1/callsheet-layouts/{layoutId} | Retrieve callsheet layout | One visible published callsheet layout root. |
POST /api/v1/callsheet-layouts | Create callsheet layout draft | Creates a saved callsheet layout draft only. |
PUT /api/v1/callsheet-layouts/{layoutId} | Update callsheet layout draft | Updates a saved callsheet layout draft when version checks pass. |
POST /api/v1/semantic-search/search | Search product docs or private canon | Citation-first search when product-doc, private-canon, add-on, credit, and scope checks allow it. |
POST /api/v1/semantic-search/context | Search product docs context | Citation-first HotRoute product-doc context search in organization scope. |
Published read-projection endpoints
The endpoints in this section are read-only projection endpoints. Each row publishes both GET /api/v1/<path> for list and GET /api/v1/<path>/{id} for retrieve. List responses use bounded pagination.
| Path | Area | Customer-safe result |
|---|---|---|
systems | Football canon | Active scheme systems scoped by playbook. |
formations | Football canon | Active formation metadata. |
personnel-groupings | Football canon | Published personnel grouping versions. |
concept-families | Football canon | Published concept-family versions. |
concepts | Football canon | Published concept versions. |
play-versions | Plays | Published play versions without workspace payloads. |
play-sequences | Football canon | Active play sequence roots. |
play-scripts | Football canon | Active play script roots. |
principles | Standards | Active principles used by standards, identity, and philosophy models. |
philosophy-models | Standards | Active philosophy model roots. |
identity-models | Standards | Active identity model roots. |
performance-standards | Standards | Active performance-standard roots. |
gameplans | Gameplans | Published gameplan roots with current published versions. |
install-packages | Install packages | Active install packages with current published versions. |
rosters | Team management | Published locked roster summaries. |
positions | Personnel | Active position catalog entries. |
personnel | Personnel | Roster-scoped safe player football metadata. |
depth-charts | Depth charts | Published locked depth-chart summaries. |
opponent-personnel | Opponent personnel | Active opponent personnel identity metadata. |
assignment-sets | Teaching and development | Published assignment-set roots. |
contextual-questions | Teaching and development | Open contextual questions with active current versions. |
contextual-answers | Teaching and development | Published contextual answers. |
practice-plans | Teaching and development | Published practice plan roots. |
practice-drills | Teaching and development | Published practice drill roots. |
teaching-deliveries | Teaching and development | Active teaching delivery events. |
teaching-receipts | Teaching and development | Safe teaching delivery receipt status. |
insights | Analysis | Active insights with published versions. |
insight-trust-evaluations | Analysis | Safe insight trust evaluation summaries. |
evidence-ref-types | Evidence | Active evidence reference source types. |
evidence-clips | Evidence | Active evidence clip segments without storage references. |
evidence-bundles | Evidence | Active evidence bundles. |
scenario-templates | Simulations | Active scenario templates when simulation access is enabled. |
simulation-profiles | Simulations | Active simulation profiles when simulation access is enabled. |
simulation-requests | Simulations | Simulation requests and scenario bindings when simulation access is enabled. |
simulation-runs | Simulations | Simulation run status summaries when simulation access is enabled. |
object-threads | Collaboration | Open object-linked collaboration threads. |
object-thread-messages | Collaboration | Non-redacted object-thread messages. |
responsibilities | Staff authority | Published responsibility definitions. |
responsibility-maps | Staff authority | Published responsibility maps. |
delegations | Staff authority | Active delegation roots. |
alignment-checks | Staff authority | Alignment checks and alert posture. |
billing/entitlements | Billing projections | Safe organization entitlement projection. |
billing/addons | Billing projections | Safe add-on entitlement projection. |
billing/credit-reminders | Billing projections | Semantic credit reminder status projection. |
compliance/policies | Compliance | Published policy document versions. |
compliance/privacy-requests | Compliance | Organization privacy request status projection. |
support/cases | Support | Safe support case projection. |
How approved requests work
An approved request usually has five pieces:
- A service-account API key stored by the customer or approved partner.
- Organization context.
- Team, season, playbook, or object context when the resource family needs it.
- The operation the tool is trying to perform, such as list, retrieve, search, render, create, update, or import preview.
- A request id, idempotency key, or version check when the route requires one.
HotRoute then checks whether the key is active, the account is still allowed, the scope covers the requested resource and operation, the plan allows the surface, the requested object is visible, and the route can safely return a response.
Safe denial states
Denied responses should be useful without exposing private state.
| Situation | What it means for the customer |
|---|---|
| Missing or revoked key | The integration is not authenticated. Create, rotate, or restore access from Manage Service Accounts. |
| Missing scope | The key was not granted that object family, action, team, season, playbook, or object boundary. An owner must decide whether to broaden scope. |
| Wrong organization or hidden object | HotRoute may refuse or return a not-found style response so one organization cannot learn about another organization's data. |
| Unavailable plan or add-on | The organization does not currently have the plan, add-on, or grant required for that route. |
| Lifecycle denied | The object is draft-only, archived, hidden, missing a published version, or otherwise not safe for this external route. |
| Rate limited | The integration sent too many requests for the current customer, service account, or route class. Retry after the indicated window when one is provided. |
| Invalid request shape | The request was malformed, too broad, missing required team or season context, missing idempotency, or failed a field-level rule. |
Do not use a denial to infer hidden object existence. If a tool receives a refusal, fix the visible scope or route the question back to an organization owner.
What good looks like
A healthy external API integration is narrow, named, and inspectable.
The owner should be able to answer:
- Which real football workflow does this integration support?
- Which team, season, and object family does it need?
- Which operation classes are necessary?
- Where is the key stored?
- Who owns rotation and revocation?
- What should the tool do when HotRoute refuses, rate limits, or returns an empty result?
Common questions or mistakes
Can an API key see every organization object?
No. A key only works inside the organization-owned scope the owner granted, and routes still check plan, role, lifecycle, visibility, and safe response rules.
Can an outside tool create or publish football truth?
Not by default. Retrieval, search, render, bounded schedule writes, callsheet layout drafts, and import preview are controlled surfaces. Review, publish, archive, billing, membership, support-admin, and platform-admin authority stay out of service-account access unless a later approved workflow says otherwise.
Can I connect outside approved HotRoute routes?
No. Approved integrations use documented HotRoute API routes. They do not receive broad backend credentials or unreviewed access paths.
Why did the route return not found when I expected an authorization error?
Sometimes hiding object existence is safer than confirming that an object exists but is unavailable. Treat either response as a sign to check scope, team, season, lifecycle, and owner approval.
Related docs / next steps
Start with Manage Service Accounts when an owner needs to create or rotate a key.
Use Install the hot CLI when the approved integration will connect through the HotRoute command-line tool.
Read Customer Agent Integrations before connecting Codex, Claude, ChatGPT, MCP, hotroute-tools, or another approved agent-style tool.
Use Retrieval and Search when the integration needs product-doc citations or customer-private canonical search.