# Pitch Connect API — Full AI Agent Specification & Tool Reference

Base URL: `https://pitch-connect.space`
OpenAPI Spec (JSON): `https://pitch-connect.space/api/openapi.json`
OpenAPI Spec (YAML): `https://pitch-connect.space/api/openapi.yaml`

---

## 1. System Prompt Context for AI Agents

You are an AI Agent integrating with Pitch Connect API.
Pitch Connect is a platform for organizing pickup sports games, managing clubs, and hosting tournaments.

### Key Concepts:
- **Connected Account Token**: Auth token representing a user account with access to multiple clubs/tournaments.
- **Club API Token**: API key scoped to a single club.
- **Tournament API Token**: API key scoped to a single tournament.
- **Tournament Match**: A scheduled or live match between two teams in a tournament.
- **Lineups**: Starting players, substitutes, and formation for each team in a match.
- **Game Marker**: Granular live match events (Goal, Card, Period, Substitution) timestamped and linked to players.

### Pickup-game junior player identity

Game roster entries expose `id`, `is_guest`, and `player_type`. `player_type` is `user` for registered players, `junior` for saved junior members, and `guest` for unnamed plus-ones that have no reusable ID. When submitting pickup-game markers for users or juniors, copy both the roster ID and its namespace:

```json
{
  "id": "client-marker-uuid",
  "match_id": "301_0",
  "timestamp": "2026-07-27T18:30:00Z",
  "type": "Goal",
  "primary_player_pc_id": 17,
  "primary_player_type": "junior"
}
```

The optional `secondary_player_type` works the same way. Omitted types are inferred from the game roster for backward compatibility, but integrations should send them because user and junior IDs use separate numeric namespaces. Junior goals, cards, shots, saves, fouls, chances, and defensive contributions are attributed to their assigned team and shown in match statistics.

---

## 2. Authentication

All requests require the Bearer token header:
`Authorization: Bearer <YOUR_API_TOKEN>`

### Third-Party OAuth Flow
To obtain a user token:
1. Direct user to:
   `GET https://pitch-connect.space/api/auth/connect?app_name=YourAppName&redirect_uri=https://myapp.com/callback`
2. After user consents, Pitch Connect redirects to:
   `https://myapp.com/callback?api_key=<TOKEN>&resource_type=account&user_name=Name&club_count=2&tournament_count=3`
3. Use `<TOKEN>` in the `Authorization: Bearer <TOKEN>` header.

---

## 3. Function Calling / Tools Definition (OpenAI Format)

```json
[
  {
    "name": "list_accessible_resources",
    "description": "Discover all clubs and tournaments accessible by the current API key.",
    "parameters": {
      "type": "object",
      "properties": {},
      "required": []
    }
  },
  {
    "name": "get_tournament_details",
    "description": "Get tournament information including status, teams, standby players, and lineups.",
    "parameters": {
      "type": "object",
      "properties": {
        "tournament_slug": { "type": "string", "description": "Slug of the tournament" }
      },
      "required": ["tournament_slug"]
    }
  },
  {
    "name": "get_tournament_matches",
    "description": "Get all matches for a tournament with current scores, lineups, goals, cards, and markers.",
    "parameters": {
      "type": "object",
      "properties": {
        "tournament_slug": { "type": "string", "description": "Slug of the tournament" }
      },
      "required": ["tournament_slug"]
    }
  },
  {
    "name": "submit_tournament_match_marker",
    "description": "Record a live event marker (Goal, Card, Substitution, Period) for a tournament match.",
    "parameters": {
      "type": "object",
      "properties": {
        "tournament_slug": { "type": "string", "description": "Slug of the tournament" },
        "match_id": { "type": "integer", "description": "ID of the tournament match" },
        "type": { "type": "string", "enum": ["Start", "Goal", "YellowCard", "RedCard", "Substitution", "Break", "Resume", "PenaltyScored", "PenaltyMissed", "PenaltyShootout", "ResetMatch"] },
        "client_id": { "type": "string", "description": "Unique client UUID for idempotency" },
        "minute": { "type": "integer", "description": "Match minute (0-120)" },
        "team_side": { "type": "string", "enum": ["home", "away"] },
        "primary_player_pc_id": { "type": "integer", "description": "Pitch Connect User ID of scorer/player" },
        "secondary_player_pc_id": { "type": "integer", "description": "Pitch Connect User ID of assister/player" }
      },
      "required": ["tournament_slug", "match_id", "type", "client_id"]
    }
  },
  {
    "name": "delete_tournament_match_marker",
    "description": "Delete a live event marker and automatically revert goal counts and match scores.",
    "parameters": {
      "type": "object",
      "properties": {
        "tournament_slug": { "type": "string", "description": "Slug of the tournament" },
        "match_id": { "type": "integer", "description": "ID of the match" },
        "id": { "type": "integer", "description": "ID or client_id of the marker to delete" }
      },
      "required": ["tournament_slug", "match_id", "id"]
    }
  }
]
```

---

## 4. Endpoints & Request/Response Schemas

### GET /api/v1/resources
**Request:**
```bash
curl -X GET "https://pitch-connect.space/api/v1/resources" \
  -H "Authorization: Bearer pc_app_token_xxx"
```
**Response (200 OK):**
```json
{
  "account_user": { "id": 12, "name": "Alex Johnson", "email": "alex@example.com" },
  "clubs": [
    { "id": 5, "name": "Apex FC", "slug": "apex-fc", "role": "owner" }
  ],
  "tournaments": [
    { "id": 3, "name": "Summer Cup 2026", "slug": "summer-cup-2026", "role": "organizer" }
  ]
}
```

---

### GET /api/v1/tournaments/:tournament_slug
**Response (200 OK):**
```json
{
  "id": 3,
  "name": "Summer Cup 2026",
  "slug": "summer-cup-2026",
  "status": "in_progress",
  "tournament_type": "intra_club",
  "teams": [
    { "id": 101, "name": "Red Dragons", "captain_id": 12 }
  ],
  "standby_players": [
    { "id": 45, "name": "Jordan Lee", "ranking": "A", "rating": 4 }
  ],
  "lineups": {
    "101": [
      { "id": 12, "name": "Alex Johnson", "position": "midfielder", "jersey_number": 10, "is_captain": true }
    ]
  }
}
```

---

### GET /api/v1/tournaments/:tournament_slug/matches
**Response (200 OK):**
```json
{
  "tournament": { "slug": "summer-cup-2026", "name": "Summer Cup 2026" },
  "matches": [
    {
      "id": 88,
      "status": "live",
      "home_team": { "id": 101, "name": "Red Dragons" },
      "away_team": { "id": 102, "name": "Blue Hawks" },
      "score": { "home": 2, "away": 1 },
      "lineups": {
        "home": [
          { "id": 12, "name": "Alex Johnson", "position": "midfielder", "jersey_number": 10, "is_captain": true }
        ],
        "away": []
      },
      "goals": [
        { "minute": 14, "team": "home", "scorer": "Alex Johnson", "assist": "Sam Lee", "marker_client_id": "uuid-123" }
      ]
    }
  ]
}
```

---

### POST /api/v1/tournaments/:tournament_slug/matches/:match_id/markers
**Request Body:**
```json
{
  "client_id": "unique-uuid-9999",
  "type": "Goal",
  "minute": 34,
  "team_side": "home",
  "primary_player_pc_id": 12,
  "secondary_player_pc_id": 45
}
```
**Response (200 OK):**
```json
{
  "status": "created",
  "marker": {
    "id": 501,
    "client_id": "unique-uuid-9999",
    "type": "Goal",
    "minute": 34,
    "team_side": "home"
  },
  "match_score": { "home": 3, "away": 1 }
}
```

---

### DELETE /api/v1/tournaments/:tournament_slug/matches/:match_id/markers/:id
**Response (200 OK):**
```json
{
  "status": "deleted",
  "message": "Marker deleted successfully and score reverted",
  "match_score": { "home": 2, "away": 1 }
}
```

---

## 5. Error Code Matrix

| HTTP Code | Error Message | Action Needed |
|---|---|---|
| 401 | `Unauthorized` | Missing or invalid Bearer token |
| 403 | `Forbidden` | Token does not have organizer/owner rights for this resource |
| 404 | `Resource Not Found` | Check tournament_slug or match_id |
| 422 | `Unprocessable Entity` | Check marker type or required parameters |

---

## 6. Code Examples for AI Agents

### Python (requests)
```python
import requests

HEADERS = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"}

# 1. Get matches
resp = requests.get("https://pitch-connect.space/api/v1/tournaments/summer-cup-2026/matches", headers=HEADERS)
matches = resp.json()["matches"]

# 2. Submit Goal Marker
marker_payload = {
    "client_id": "marker-uuid-001",
    "type": "Goal",
    "minute": 15,
    "team_side": "home",
    "primary_player_pc_id": 12
}
res = requests.post(
    "https://pitch-connect.space/api/v1/tournaments/summer-cup-2026/matches/88/markers",
    headers=HEADERS,
    json=marker_payload
)
print(res.json())
```

### TypeScript / Node.js (fetch)
```typescript
const token = "YOUR_TOKEN";
const headers = {
  "Authorization": `Bearer ${token}`,
  "Content-Type": "application/json"
};

async function getMatches(slug: string) {
  const res = await fetch(`https://pitch-connect.space/api/v1/tournaments/${slug}/matches`, { headers });
  return await res.json();
}
```

### Swift (URLSession)
```swift
var request = URLRequest(url: URL(string: "https://pitch-connect.space/api/v1/tournaments/summer-cup-2026/matches")!)
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
let (data, _) = try await URLSession.shared.data(for: request)
```