# Middle Folio

> Générateur de portfolios en ligne (CV, portfolios thémables, recrutement). API REST v1 pour piloter son compte : portfolios, CV, entreprises, offres, candidatures.

## Documentation
- [Documentation de l’API](https://middlefolio.online/docs/api) : démarrage, authentification, opérations.
- [OpenAPI](https://middlefolio.online/api/v1/openapi.json) : spécification complète (OpenAPI 3.1), avec un exemple réel de requête et de réponse (et le schéma qui en découle) pour chaque opération.
- [MCP](https://middlefolio.online/api/v1/mcp) : serveur MCP HTTP (Bearer = clé API), un outil par opération.
- [Skill](https://middlefolio.online/docs/api/skill) : skill Claude « middle-folio-api » (.zip).
- [Pont MCP stdio](https://middlefolio.online/docs/api/mcp) : script Node sans dépendance pour les clients MCP stdio.

- [Comment ça marche](https://middlefolio.online/aide) : guides en français (portfolio, CV, entreprise, offres d’emploi, candidatures, formules).

## Authentification
Clé API personnelle créée dans API > Gérer (`Authorization: Bearer <clé>`). Clés `mf_test_…` : mode test, rien n’est enregistré.

## Conventions
Réponses `{ "data": … }` ; URL absolues ; `public_url` pointe vers le sous-domaine du portfolio s’il en a réservé un, sinon vers `/p/{slug}` ; le nom affiché publiquement est le nom de marque s’il est renseigné ; horaires d’ouverture (`opening_hours`) en texte libre.

## Opérations

### Compte
- `GET /api/v1/me` — Profil du titulaire de la clé.
- `PATCH /api/v1/me` — Modifie le profil (l’e-mail principal et la photo restent réservés à l’interface web).
- `PATCH /api/v1/me/locale` — Change la langue du compte (interface et e-mails).
- `PUT /api/v1/me/photo` — Définit la photo de profil (image de la bibliothèque, copiée vers la photo du compte).
- `DELETE /api/v1/me/photo` — Retire la photo de profil.
- `GET /api/v1/me/plan` — Formule courante, capacités (quotas, droits) et usage du compte.
- `GET /api/v1/me/key` — Permissions de la clé utilisée : niveau par zone et entreprises autorisées.
- `GET /api/v1/me/referral` — Code et lien de parrainage, nombre de filleuls (lecture seule).

### Fichiers
- `GET /api/v1/files` — Bibliothèque de fichiers : fournit les identifiants pour les champs *_media_ids et media_id.
- `POST /api/v1/files` — Téléverse une image (jpg, png, webp, gif) ou un PDF dans la bibliothèque et renvoie son identifiant.
- `DELETE /api/v1/files/{media}` — Supprime définitivement un fichier de la bibliothèque (et tous ses rattachements).

### Référentiels
- `GET /api/v1/categories` — Catégories de l’annuaire, arbre aplati (parent_id, depth) : identifiants pour categories (portfolio) et category_ids (entreprise, offre).
- `GET /api/v1/portfolio-icons` — Bibliothèque d’icônes utilisable : icônes globales et les vôtres, identifiants pour icon_id d’une entrée de portfolio.
- `POST /api/v1/portfolio-icons` — Ajoute une icône personnalisée à votre bibliothèque (50 max par compte).
- `DELETE /api/v1/portfolio-icons/{icon}` — Supprime une de vos icônes personnalisées (les entrées qui l’utilisent la perdent).

### Portfolios
- `GET /api/v1/portfolios` — Liste vos portfolios personnels.
- `POST /api/v1/portfolios` — Crée un portfolio avec ses sections par défaut (quota du plan appliqué).
- `GET /api/v1/portfolios/{portfolio}` — Portfolio complet : sections et entrées.
- `PATCH /api/v1/portfolios/{portfolio}` — Modifie les informations générales du portfolio.
- `POST /api/v1/portfolios/{portfolio}/duplicate` — Duplique un portfolio personnel : contenu, thème, fichiers et réglages (quota du plan appliqué).
- `DELETE /api/v1/portfolios/{portfolio}` — Supprime le portfolio (suppression logique, non restaurable depuis l’API).
- `PUT /api/v1/portfolios/{portfolio}/logo` — Définit le logo (image de la bibliothèque).
- `DELETE /api/v1/portfolios/{portfolio}/logo` — Retire le logo.
- `PUT /api/v1/portfolios/{portfolio}/favicon` — Définit la favicon (image de la bibliothèque), recompressée si elle dépasse le poids maximal.
- `DELETE /api/v1/portfolios/{portfolio}/favicon` — Retire la favicon (le site reprend celle de la plateforme).
- `PUT /api/v1/portfolios/{portfolio}/hero-image` — Définit l’image principale (image de la bibliothèque).
- `DELETE /api/v1/portfolios/{portfolio}/hero-image` — Retire l’image principale.

### Contenu du portfolio
- `POST /api/v1/portfolios/{portfolio}/sections` — Ajoute une section en fin de liste.
- `PUT /api/v1/portfolios/{portfolio}/sections/reorder` — Réordonne les sections.
- `POST /api/v1/portfolio-sections/{section}/insert-after` — Insère une section juste après {section}.
- `PATCH /api/v1/portfolio-sections/{section}` — Modifie titre, visibilité et mode d’affichage d’une section.
- `DELETE /api/v1/portfolio-sections/{section}` — Supprime une section et ses entrées.
- `POST /api/v1/portfolio-sections/{section}/entries` — Ajoute une entrée à une section (limite du plan appliquée).
- `PUT /api/v1/portfolio-sections/{section}/entries/reorder` — Réordonne les entrées d’une section.
- `PATCH /api/v1/portfolio-entries/{entry}` — Modifie une entrée.
- `DELETE /api/v1/portfolio-entries/{entry}` — Supprime une entrée.
- `DELETE /api/v1/portfolio-entries/{entry}/media/{media}` — Retire un média d’une entrée (le fichier reste dans la bibliothèque).

### Thème et publication
- `GET /api/v1/portfolios/{portfolio}/theme` — Thème du portfolio (couleurs, polices, gabarit).
- `PATCH /api/v1/portfolios/{portfolio}/theme` — Modifie le thème (couleurs, polices, échelles, gabarit).
- `GET /api/v1/portfolios/{portfolio}/theme/templates` — Gabarits proposés, avec leur verrouillage selon la formule (allowed).
- `PUT /api/v1/portfolios/{portfolio}/theme/templates` — Change uniquement le gabarit.
- `GET /api/v1/portfolios/{portfolio}/publishing` — Réglages de publication et état (publié ou non).
- `PATCH /api/v1/portfolios/{portfolio}/publishing` — Modifie les réglages de publication.
- `POST /api/v1/portfolios/{portfolio}/publishing/publish` — Publie le portfolio (le plan doit inclure un site public).
- `POST /api/v1/portfolios/{portfolio}/publishing/unpublish` — Dépublie le portfolio.

### CV
- `GET /api/v1/cvs` — Liste vos CV.
- `GET /api/v1/cv-templates` — Gabarits de CV proposés à ce compte.
- `POST /api/v1/cvs` — Crée un CV vide ou copié depuis un portfolio (quota max_cvs).
- `GET /api/v1/cvs/{cv}` — CV complet : sections et entrées.
- `PATCH /api/v1/cvs/{cv}` — Modifie identité et coordonnées du CV.
- `PATCH /api/v1/cvs/{cv}/appearance` — Modifie l’apparence du CV.
- `PUT /api/v1/cvs/{cv}/template` — Change le gabarit du CV.
- `PUT /api/v1/cvs/{cv}/photo` — Définit la photo du CV (image de la bibliothèque).
- `DELETE /api/v1/cvs/{cv}/photo` — Retire la photo du CV.
- `DELETE /api/v1/cvs/{cv}` — Supprime le CV (suppression logique).
- `GET /api/v1/cvs/{cv}/export` — Télécharge le CV en PDF (binaire ; indisponible en mode test).

### Contenu du CV
- `POST /api/v1/cvs/{cv}/sections` — Ajoute une section en fin de liste ; renvoie le CV complet.
- `PUT /api/v1/cvs/{cv}/sections/reorder` — Réordonne les sections.
- `POST /api/v1/cv-sections/{section}/insert-after` — Insère une section après {section}.
- `PATCH /api/v1/cv-sections/{section}` — Modifie titre, visibilité, colonne.
- `DELETE /api/v1/cv-sections/{section}` — Supprime une section.
- `POST /api/v1/cv-sections/{section}/entries` — Ajoute une entrée ; renvoie le CV complet.
- `PUT /api/v1/cv-sections/{section}/entries/reorder` — Réordonne les entrées.
- `PATCH /api/v1/cv-entries/{entry}` — Modifie une entrée ; renvoie le CV complet.
- `DELETE /api/v1/cv-entries/{entry}` — Supprime une entrée.

### Entreprises
- `GET /api/v1/companies` — Entreprises que vous gérez.
- `POST /api/v1/companies` — Crée une entreprise (quota max_companies).
- `GET /api/v1/companies/{company}` — Détail d’une entreprise et de ses gestionnaires.
- `PATCH /api/v1/companies/{company}` — Modifie les informations de l’entreprise.
- `POST /api/v1/companies/{company}/duplicate` — Duplique une entreprise dont vous êtes propriétaire : fiche, catégories, logo, favicon et site dédié (quota max_companies).
- `PUT /api/v1/companies/{company}/logo` — Définit le logo de l’entreprise (image de la bibliothèque).
- `DELETE /api/v1/companies/{company}/logo` — Retire le logo de l’entreprise.
- `PUT /api/v1/companies/{company}/favicon` — Définit la favicon de l’entreprise et de son site (image de la bibliothèque), recompressée si elle dépasse le poids maximal.
- `DELETE /api/v1/companies/{company}/favicon` — Retire la favicon de l’entreprise (son site reprend alors le logo).
- `POST /api/v1/companies/{company}/members` — Ajoute un gestionnaire (compte existant).
- `DELETE /api/v1/companies/{company}/members/{user}` — Retire un gestionnaire (pas le fondateur).
- `POST /api/v1/companies/{company}/site` — Crée le site dédié ; son contenu se gère ensuite via les routes portfolios (portfolio_id).

### Offres d’emploi
- `GET /api/v1/companies/{company}/offers` — Offres de l’entreprise.
- `POST /api/v1/companies/{company}/offers` — Publie une offre.
- `GET /api/v1/companies/{company}/offers/{jobOffer}` — Détail d’une offre.
- `PATCH /api/v1/companies/{company}/offers/{jobOffer}` — Modifie une offre (is_active: false la clôture).
- `DELETE /api/v1/companies/{company}/offers/{jobOffer}` — Archive l’offre.

### Offres externes
- `GET /api/v1/external-offers` — Offres externes que vous avez soumises (tous statuts).
- `POST /api/v1/external-offers` — Soumet une offre publiée ailleurs (candidature hors plateforme).
- `GET /api/v1/external-offers/{externalJobOffer}` — Détail d’une de vos offres externes (statut et motif de rejet inclus).
- `PATCH /api/v1/external-offers/{externalJobOffer}` — Modifie une de vos offres externes.
- `DELETE /api/v1/external-offers/{externalJobOffer}` — Supprime une de vos offres externes.
- `PUT /api/v1/external-offers/{externalJobOffer}/logo` — Définit le logo de l’offre (image de la bibliothèque) ; l’offre repasse « pending ».
- `PUT /api/v1/external-offers/{externalJobOffer}/document` — Définit le document complémentaire de l’offre (fichier de la bibliothèque, public) ; l’offre repasse « pending ».
- `DELETE /api/v1/external-offers/{externalJobOffer}/document` — Retire le document complémentaire de l’offre.
- `DELETE /api/v1/external-offers/{externalJobOffer}/logo` — Retire le logo de l’offre.

### Candidatures reçues
- `GET /api/v1/companies/{company}/applications` — Candidatures reçues par l’entreprise.
- `GET /api/v1/companies/{company}/applications/{application}` — Détail d’une candidature (pièces jointes non exposées).
- `PATCH /api/v1/companies/{company}/applications/{application}/status` — Change le statut d’une candidature.