# Pitch Connect API — LLM & AI Agent Context

> Pitch Connect is a sports tournament, pickup game, and club management platform. This document provides a machine-readable summary of the Pitch Connect API for AI Agents, LLM assistants, and automated integrations.

## System Overview
- **Base URL**: `https://pitch-connect.space`
- **API Spec**: `https://pitch-connect.space/api/openapi.yaml` (YAML) | `https://pitch-connect.space/api/openapi.json` (JSON)
- **Full LLM Context**: `https://pitch-connect.space/llms-full.txt`
- **Interactive Documentation**: `https://pitch-connect.space/api/docs/interactive`
- **Authentication**: HTTP Bearer Token (`Authorization: Bearer <token>`)

---

## Authentication & Authorization
Pitch Connect uses Bearer Tokens in the `Authorization` header:
`Authorization: Bearer <your_api_key>`

### Obtaining an API Token
1. **OAuth Connection Flow (Third-Party Apps & Agents)**:
   Redirect user to: `GET https://pitch-connect.space/api/auth/connect?app_name=YourAgentName&redirect_uri=https://your-agent.com/callback`
   Upon approval, Pitch Connect redirects to `redirect_uri` with `?api_key=<token>&resource_type=account`.
2. **Static API Key**:
   Generated in Pitch Connect Club or Tournament Settings -> Integrations page.

---

## Core API Endpoints

### 1. Resources Discovery (Connected Account)
- `GET /api/v1/resources`: Lists all clubs and tournaments accessible by the current API key.

### 2. Tournaments API
- `GET /api/v1/tournaments/:tournament_slug`: Retrieve full tournament details, status, teams, standby players, and lineups.
- `GET /api/v1/tournaments/:tournament_slug/matches`: Retrieve all matches for a tournament, including live scores, lineups, goals, cards, and markers.
- `POST /api/v1/tournaments/:tournament_slug/matches/:match_id/markers`: Submit a live event marker (Goal, YellowCard, RedCard, Substitution, Period, etc.) to a tournament match.
- `DELETE /api/v1/tournaments/:tournament_slug/matches/:match_id/markers/:id`: Delete a marker and automatically revert associated score and stats.

### 3. Pickup & Club Games API
- `GET /api/v1/clubs/:club_slug/games/:slug`: Get details for a pickup game.
- `GET /api/v1/clubs/:club_slug/upcoming_games`: List upcoming games for a club.
- `GET /api/v1/clubs/:club_slug/past_games`: List past games for a club.
- `POST /api/v1/clubs/:club_slug/games/:slug/markers`: Submit a live event marker for a pickup game.
- `DELETE /api/v1/clubs/:club_slug/games/:slug/markers/:id`: Delete a pickup game event marker and revert score/stats.

Pickup-game roster entries include `player_type` (`user`, `junior`, or `guest`). Entries of type `guest` have no reusable ID. For users and juniors, copy both the roster `id` and `player_type` into marker player fields; for example, use `primary_player_pc_id: 17` with `primary_player_type: "junior"`. Junior markers are included in team scores, timelines, and match stats.

### 4. Highlights API
- `GET /api/v1/clubs/:club_slug/games/:slug/highlights`: Retrieve game highlights.
- `POST /api/v1/clubs/:club_slug/games/:slug/highlight`: Submit a new video/photo highlight for a game.

---

## Event Marker Types
Valid marker types for match events:
- `Start`, `Goal`, `YellowCard`, `RedCard`, `Substitution`, `Break`, `Resume`, `PenaltyScored`, `PenaltyMissed`, `PenaltyShootout`, `ResetMatch`

## Standard Headers
- `Authorization`: `Bearer <token>`
- `Content-Type`: `application/json`
- `Accept`: `application/json`

---

## AI Agent Integration Guidelines
For complete LLM instructions, JSON schemas, function definitions, and prompt templates, visit:
- **Full LLM Spec**: `https://pitch-connect.space/llms-full.txt`
- **AI Agent Docs**: `https://pitch-connect.space/api/docs/ai`