Portail développeur

API publique v1

Une API REST publique, en lecture seule, pour consommer les données de tournois, matchs, équipes, classements et ligues. Sans clé, versionnée, prête à intégrer dans vos overlays, bots et sites.

Vue d'ensemble

Lecture seule

Les routes de lecture sont en GET, sans clé. L'écriture, elle, requiert un token scopé (voir plus bas).

Sans authentification

Aucune clé d'API ni jeton requis. Appelez directement les endpoints.

CORS ouvert

En-tête Access-Control-Allow-Origin: * — utilisable depuis un navigateur.

Versionnée

Préfixe /api/public/v1. La v1 reste stable ; toute rupture passera par une v2.

Rate-limit

Environ 120 requêtes par minute et par adresse IP. Au-delà : erreur RATE_LIMITED.

Réponses JSON en enveloppe

Le contenu est toujours sous { data: ... }. Les listes ajoutent un objet pagination.

Écriture authentifiée

Un token Bearer pk_live_… scopé autorise l'écriture : report de score, et bientôt plus.

GraphQL

Un endpoint GraphQL unique : requêtes anonymes, mutations sur token scopé.

Base URL

L'API est servie depuis l'origine du site. Toutes les routes sont préfixées par /api/public/v1.

https://owwomenscup.fr/api/public/v1

Format des erreurs

Une erreur renvoie un statut HTTP adapté et un corps JSON { error, code }.

code	Signification
`NOT_FOUND`	Ressource introuvable.
`BAD_REQUEST`	Paramètres invalides ou manquants.
`METHOD_NOT_ALLOWED`	Méthode HTTP non autorisée (seul GET est supporté).
`RATE_LIMITED`	Limite de requêtes dépassée. Réessayez plus tard.
`INTERNAL`	Erreur interne du serveur.

Exemple rapide

Récupérer les tournois en cours. La réponse expose la liste sous data et les métadonnées de pagination sous pagination.

curl

curl -s "https://owwomenscup.fr/api/public/v1/tournaments?status=running&limit=10"

JavaScript (fetch)

const res = await fetch(
  "https://owwomenscup.fr/api/public/v1/tournaments?status=running&limit=10"
);
const { data, pagination } = await res.json();
// data       -> TournamentSummary[]
// pagination -> { limit, offset, count }
console.log(data.length, pagination.count);

Référence des endpoints

Voir la référence complète générée →

Tournois

Liste, détail et déroulé compétitif d'un tournoi. L'identifiant accepte l'UUID ou le slug.

GET/api/public/v1/tournaments

Liste des tournois publics.

Paramètres de /api/public/v1/tournaments
Paramètre	Emplacement	Description
`status`	requête	Filtre par statut (ex. running, completed).
`game`	requête	Filtre par jeu (ex. overwatch).
`limit`	requête	Taille de page (pagination).
`offset`	requête	Décalage de départ (pagination).

Réponse

{
  "data": [
    {
      "id": "uuid",
      "name": "OW Women's Cup 2026",
      "slug": "ow-womens-cup-2026",
      "game": "overwatch",
      "status": "running",
      "start_date": "2026-01-01",
      "end_date": "2026-02-01",
      "format": "single_elimination"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "count": 42 }
}

GET/api/public/v1/tournaments/{id}

Détail d'un tournoi et ses phases (stages).

Paramètres de /api/public/v1/tournaments/{id}
Paramètre	Emplacement	Description
`id`requis	chemin	Identifiant du tournoi : UUID ou slug.

Réponse

{
  "data": {
    "id": "uuid",
    "name": "OW Women's Cup 2026",
    "slug": "ow-womens-cup-2026",
    "game": "overwatch",
    "status": "running",
    "start_date": "2026-01-01",
    "end_date": "2026-02-01",
    "format": "single_elimination",
    "stages": [
      { "id": "uuid", "name": "Phase de groupes", "stage_type": "group", "status": "completed" }
    ]
  }
}

GET/api/public/v1/tournaments/{id}/matches

Matchs d'un tournoi.

Paramètres de /api/public/v1/tournaments/{id}/matches
Paramètre	Emplacement	Description
`id`requis	chemin	UUID ou slug du tournoi.
`stageId`	requête	Filtre par phase (id de stage).
`status`	requête	Filtre par statut de match.

Réponse

{
  "data": [
    {
      "id": "uuid",
      "stage_id": "uuid",
      "round_number": 1,
      "bracket_side": "upper",
      "team1_id": "uuid",
      "team1_name": "Team A",
      "team2_id": "uuid",
      "team2_name": "Team B",
      "team1_score": 2,
      "team2_score": 1,
      "winner_team_id": "uuid",
      "status": "finished",
      "scheduled_at": "2026-01-05T18:00:00Z"
    }
  ]
}

GET/api/public/v1/tournaments/{id}/standings

Classement final d'un tournoi (vide tant qu'il n'est pas finalisé).

Paramètres de /api/public/v1/tournaments/{id}/standings
Paramètre	Emplacement	Description
`id`requis	chemin	UUID ou slug du tournoi.

Réponse

{
  "data": [
    {
      "rank": 1,
      "teamId": "uuid",
      "teamName": "Team A",
      "teamSlug": "team-a",
      "logoUrl": "https://.../logo.png",
      "prize": "500 €"
    }
  ]
}

Matchs

Détail d'un match, avec le score par carte (games).

GET/api/public/v1/matches/{id}

Détail d'un match et ses cartes.

Paramètres de /api/public/v1/matches/{id}
Paramètre	Emplacement	Description
`id`requis	chemin	UUID du match.

Réponse

{
  "data": {
    "id": "uuid",
    "stage_id": "uuid",
    "round_number": 1,
    "bracket_side": "upper",
    "team1_id": "uuid",
    "team1_name": "Team A",
    "team2_id": "uuid",
    "team2_name": "Team B",
    "team1_score": 2,
    "team2_score": 1,
    "winner_team_id": "uuid",
    "status": "finished",
    "scheduled_at": "2026-01-05T18:00:00Z",
    "games": [
      { "map_name": "Ilios", "map_order": 1, "team1_score": 2, "team2_score": 1, "winner_team_id": "uuid" }
    ]
  }
}

Équipes

Fiche publique d'une équipe et son roster. L'identifiant accepte l'UUID ou le slug.

GET/api/public/v1/teams/{id}

Détail d'une équipe et sa composition.

Paramètres de /api/public/v1/teams/{id}
Paramètre	Emplacement	Description
`id`requis	chemin	UUID ou slug de l'équipe.

Réponse

{
  "data": {
    "id": "uuid",
    "name": "Team A",
    "short_name": "TMA",
    "slug": "team-a",
    "logo_url": "https://.../logo.png",
    "roster": [
      { "display_name": "Joueuse", "role": "tank", "is_substitute": false }
    ]
  }
}

Classement & profils

Classement des joueuses (rating Glicko-2) et profil individuel : historique, matchs récents, confrontations et distinctions.

GET/api/public/v1/leaderboard

Classement des joueuses.

Paramètres de /api/public/v1/leaderboard
Paramètre	Emplacement	Description
`limit`	requête	Taille de page (pagination).
`offset`	requête	Décalage de départ (pagination).

Réponse

{
  "data": [
    {
      "userId": "uuid",
      "displayName": "Joueuse",
      "battleTag": "Joueuse#1234",
      "avatarUrl": "https://.../avatar.png",
      "rating": 1650,
      "rd": 80,
      "gamesPlayed": 42,
      "wins": 28,
      "losses": 14,
      "rank": 1
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "count": 120 }
}

GET/api/public/v1/players/{userId}

Profil détaillé d'une joueuse.

Paramètres de /api/public/v1/players/{userId}
Paramètre	Emplacement	Description
`userId`requis	chemin	Identifiant de la joueuse.

Réponse

{
  "data": {
    "player": { "userId": "uuid", "displayName": "Joueuse", "rating": 1650 },
    "history": [ /* évolution du rating */ ],
    "recentMatches": [ /* derniers matchs */ ],
    "h2h": [ /* confrontations directes */ ],
    "achievements": { /* distinctions */ }
  }
}

Ligues

Liste des ligues publiques et détail d'une ligue (classement + tournois rattachés).

GET/api/public/v1/leagues

Liste des ligues publiques.

Réponse

{
  "data": [
    { "id": "uuid", "name": "Ligue Élite", "slug": "ligue-elite", "status": "running" }
  ]
}

GET/api/public/v1/leagues/{slug}

Détail d'une ligue.

Paramètres de /api/public/v1/leagues/{slug}
Paramètre	Emplacement	Description
`slug`requis	chemin	Slug de la ligue.

Réponse

{
  "data": {
    "league": { "id": "uuid", "name": "Ligue Élite", "slug": "ligue-elite" },
    "standings": [ /* classement de la ligue */ ],
    "tournaments": [ /* tournois rattachés */ ]
  }
}

Écriture authentifiée (REST)

En complément de la lecture anonyme, une surface d'écriture permet aux orgas tierces d'automatiser leurs opérations (report de résultats, overlays, intégrations). Chaque requête est authentifiée par un token scopé.

Créez votre clé API

Les clés API sont en libre-service : un administrateur de votre organisation les crée depuis l'espace admin (Réglages → Clés API). Chaque clé porte ses scopes et n'est affichée qu'une seule fois à la création. La lecture publique, elle, reste ouverte à tous, sans clé.

Créer une clé API

Authentification

Chaque écriture porte un en-tête Authorization: Bearer pk_live_…. Les tokens sont émis par un administrateur de l'organisation depuis l'espace admin et ne sont affichés qu'une seule fois à la création. Le tenant visé est déterminé par le token — aucun en-tête supplémentaire n'est requis.

Authorization: Bearer pk_live_…

Scopes

Un token porte une liste de scopes au format resource:action. Chaque endpoint déclare le scope qu'il exige ; un scope absent renvoie 403 INSUFFICIENT_SCOPE. Aucune implication : matches:write n'implique pas matches:read.

Ressource	Actions
`tournaments`	`tournaments:readtournaments:write`
`matches`	`matches:readmatches:write`
`teams`	`teams:readteams:write`
`players`	`players:readplayers:write`

Codes d'erreur (écriture)

Les écritures partagent l'enveloppe { error, code } et ajoutent les codes suivants aux codes de lecture ci-dessus.

HTTP	code	Signification
401	`UNAUTHORIZED`	Token absent, invalide ou révoqué.
403	`INSUFFICIENT_SCOPE`	Token valide, mais le scope requis est absent.
409	`CONFLICT`	Conflit d'état (par ex. un match déjà clôturé).
503	`MAINTENANCE_MODE`	Écritures gelées : le site est en mode maintenance.

Les codes de lecture (NOT_FOUND, BAD_REQUEST, RATE_LIMITED, INTERNAL…) s'appliquent également.

Idempotence

Envoyez un en-tête Idempotency-Key (≤ 200 caractères) pour sécuriser les rejeux. Une réponse 2xx est mise en cache 5 minutes et rejouée à l'identique (en-tête Idempotency-Replay: true) pour la même clé et le même corps.

POST/api/public/v1/matches/{id}/resultScope requis: matches:write

Pose le score final d'un match (autorité directe, sans consensus capitaine). Le match passe au statut finished, le bracket est propagé et les notifications sont émises. Idempotent.

Corps de la requête

{ "team1Score": 2, "team2Score": 1 }

curl

curl -X POST "https://owwomenscup.fr/api/public/v1/matches/{id}/result" \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-2026-01-05-42" \
  -d '{ "team1Score": 2, "team2Score": 1 }'

Réponse

{
  "data": {
    "matchId": "uuid",
    "status": "finished",
    "team1Score": 2,
    "team2Score": 1,
    "winnerTeamId": "uuid"
  }
}

GraphQL

Un unique endpoint POST /api/graphql sert l'API GraphQL. Les requêtes (queries) sont anonymes, comme l'API REST de lecture ; les mutations exigent un token scopé.

POST/api/graphql

GraphiQL et l'introspection sont disponibles en développement uniquement. La profondeur des requêtes est plafonnée à 8 niveaux.

Schéma (extrait)

SDL

type Query {
  tournaments(status: String, game: String, limit: Int = 50, offset: Int = 0): TournamentList!
  tournament(idOrSlug: String!): TournamentDetail   # id OU slug
  match(id: ID!): MatchDetail
  team(idOrSlug: String!): Team
}

type Mutation {
  # scope requis : matches:write
  reportMatchResult(matchId: ID!, team1Score: Int!, team2Score: Int!): MatchResultPayload!
}

Exemples

Requête (curl)

curl -X POST "https://owwomenscup.fr/api/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ tournaments(status:\"running\", limit: 10) { items { id name slug status } count } }"}'

Mutation (curl)

curl -X POST "https://owwomenscup.fr/api/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pk_live_…" \
  -d '{"query":"mutation($m:ID!){reportMatchResult(matchId:$m,team1Score:2,team2Score:1){status winnerTeamId}}","variables":{"m":"…"}}'

Explorez le schéma de façon interactive avec GraphiQL (disponible en développement uniquement).

À noter

API en lecture seule.
Le contrat de référence est décrit dans openapi.yaml.
Les endpoints sont susceptibles d'évoluer ; la version v1 reste stable.

Une question ou un cas d'usage ? Contactez-nous.