Documentation API

Environnements

L'API est disponible sur /api/v2 sur les environnements de pré-production et de production, soit les URL de base suivantes :

• En pré-production : https://staging.1eleve1stage.education.gouv.fr/api/v2
• En production : https://1eleve1stage.education.gouv.fr/api/v2

Dans les exemples ci-dessous, $BASE_URL désigne l'URL de base de l'environnement utilisé.

Authentification

Les API sont ouvertes uniquement aux acteurs concernés.

L'authentification se fait par token via le header HTTP Authorization: Bearer #{token}. Ce token devra être présent à chaque requête.

L'utilisation est limitée à 100 appels par minute, au-delà une erreur 429 est renvoyée.

Vous avez la possibilité, lors de la création de votre compte, de préciser si vous souhaitez que l'ensemble de vos offres soient retournées via la fonction recherche de l'API pour les autres partenaires. Par défaut, toutes les offres sont publiques et visibles par les autres partenaires utilisant l'API.

Comment récupérer mon token d'authentification

Un token d'authentification est nécessaire pour accéder aux endpoints de l'API. Nous utilisons des JWT pour l'authentification, valables 24 heures.

POST$BASE_URL/auth/login

Paramètres de body :

• email (chaîne, obligatoire)
• password (chaîne, obligatoire)

Exemple curl

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"email": "votre-email@example.com", "password": "votre-mot-de-passe"}' \
     $BASE_URL/auth/login

Exemple de réponse :

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MTc5MzIwMzksInN1YiI6IjEifQ.687468746874687468746874687468746874"
}

Structures de données et référentiels

Offres de stage

Les offres de stage décrites ci-dessous sont réservées aux classes de quatrième , troisième et seconde générale et technologique . La colonne « À la création » indique si l'attribut est obligatoire lors de la création d'une offre.

Semaines

Les stages se faisant sur des cycles hebdomadaires de travail (du lundi au vendredi), cette information est codifiée selon la norme ISO 8601.

Exemple : 2025-W20 correspond à l'année 2025, semaine numéro 20, du 12 au 18 mai 2025.

Exemple de ce que nous attendons dans nos API :

internship_offer.weeks: ["2025-W20", "2025-W21", "2025-W22"]

Secteurs d'activité

L'API attend en paramètre obligatoire un secteur d'activité associé à une offre. Voici la liste ainsi que leurs identifiants uniques.

Exemple de ce que nous attendons dans nos API :

internship_offer.sector_uuid: "s33"

Niveaux scolaires

Les offres de stage peuvent être proposées pour trois niveaux scolaires différents : quatrième, troisième et seconde. Voici les identifiants uniques associés à chaque niveau :

• quatrième : quatrieme
• troisième : troisieme
• seconde : seconde

Exemple de ce que nous attendons dans nos appels API :

internship_offer.grades: ["troisieme", "quatrieme"]

ou

internship_offer.grades: ["seconde"]

Horaires quotidiens

Les stages se déroulant sur une semaine du lundi au vendredi, il est possible de préciser les horaires de chaque journée de la façon suivante :

{ JOUR: [HEURE_DEBUT, HEURE_FIN] }

Exemple de ce que nous attendons dans nos API :

internship_offer.daily_hours: {
  "lundi": ["8:30", "17:00"],
  "mardi": ["8:30", "17:00"],
  "mercredi": ["8:30", "17:00"],
  "jeudi": ["8:30", "17:00"],
  "vendredi": ["8:30", "17:00"]
}

Gestion d'erreurs

Les erreurs de requête sont signalées via un code HTTP supérieur ou égal à 400. Sur chaque requête, on pourra avoir les erreurs suivantes :

En plus de ces erreurs transverses, les erreurs spécifiques à un appel sont détaillées pour chacun d'entre eux.

Endpoints

Création d'une offre

POST$BASE_URL/internship_offers

Paramètres de body : voir les attributs d'une offre de stage ; les attributs marqués « Obligatoire » sont requis.

Exemple curl

curl -H "Authorization: Bearer $API_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"internship_offer": {
           "title": "Découverte du métier de développeur web",
           "description": "Venez découvrir le métier de développeur web au sein de notre agence.",
           "employer_name": "ACME",
           "employer_description": "Agence web",
           "employer_website": "https://www.example.com",
           "siret": "11122233300000",
           "street": "128 rue de Brancion",
           "zipcode": "75015",
           "city": "Paris",
           "coordinates": {"latitude": 48.8317, "longitude": 2.3061},
           "sector_uuid": "s31",
           "weeks": ["2026-W25", "2026-W26"],
           "grades": ["seconde"],
           "remote_id": "1234",
           "permalink": "https://www.example.com/stages/1234",
           "max_candidates": 2,
           "is_public": false
         }}' \
     $BASE_URL/internship_offers

Erreurs

• 409 Conflict : une offre avec le même remote_id existe déjà

Récupérer mes offres

GET$BASE_URL/internship_offers

Exemple curl

curl -H "Authorization: Bearer $API_TOKEN" \
     -H "Accept: application/json" \
     $BASE_URL/internship_offers

Recherche d'offres

GET$BASE_URL/internship_offers/search

Paramètres d'URL :

• latitude (flottant, optionnel) : latitude du point de recherche
• longitude (flottant, optionnel) : longitude du point de recherche
• radius (entier, optionnel) : le rayon de recherche en mètres
• keyword (chaîne, optionnel) : les mots-clés à rechercher dans le titre et la description des offres

Exemple curl

curl -H "Authorization: Bearer $API_TOKEN" \
     -H "Accept: application/json" \
     "$BASE_URL/internship_offers/search?latitude=44.8624&longitude=-0.5848&radius=10000&keyword=avocat"

Modification d'une offre

PATCH$BASE_URL/internship_offers/$REMOTE_ID

L'offre est identifiée par son remote_id dans l'URL. Tous les attributs d'une offre de stage sont modifiables individuellement, aucun n'est obligatoire.

Note : la dépublication s'opère en passant null dans le paramètre published_at.

Exemple curl

curl -H "Authorization: Bearer $API_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '{"internship_offer": {"title": "Mon offre de stage", "description": "Description mise à jour"}}' \
     $BASE_URL/internship_offers/$REMOTE_ID

Erreurs

• 404 Not Found : aucune offre n'a été trouvée avec le remote_id spécifié
• 422 Unprocessable Entity : aucun paramètre n'a été spécifié pour la modification

Suppression d'une offre

DELETE$BASE_URL/internship_offers/$REMOTE_ID

L'offre est identifiée par son remote_id dans l'URL.

Exemple curl

curl -H "Authorization: Bearer $API_TOKEN" \
     -H "Accept: application/json" \
     -X DELETE \
     $BASE_URL/internship_offers/$REMOTE_ID

Erreurs

• 404 Not Found : aucune offre n'a été trouvée avec le remote_id spécifié