# DAMDesk

> Photothèque d'entreprise. Stocke des images, des vidéos et des documents,
> et sait qui a le droit de les utiliser — c'est cette dernière partie qui la
> distingue d'un simple stockage de fichiers.

## Comment s'authentifier

Toutes les requêtes portent une clé d'API, créée par le client dans
Réglages → API et IA :

    Authorization: Bearer dk_live_…

Une clé porte des PORTÉES (ce qu'elle peut faire) et, souvent, une liste
blanche de DOSSIERS (où elle peut le faire). Commencez toujours par :

    GET https://damdesk.com/v1/moi

Vous y lirez exactement ce que vous avez le droit de faire. Ne devinez pas.

## La règle à ne jamais enfreindre

Chaque fichier rendu par l'API porte un objet `utilisation` :

    "utilisation": {
      "autorise": false,
      "raison": "Les droits ont expiré le 01/03/2026. Renouvelez la licence avant toute réutilisation.",
      "credit": "© Studio Ninon"
    }

**Ne proposez jamais un fichier dont `autorise` vaut `false`.** Recopiez la
`raison` à l'utilisateur : elle est rédigée pour ça. Quand `credit` est
rempli, la mention doit accompagner toute diffusion.

`GET /v1/assets/{id}/contenu` refuse d'ailleurs de servir les octets d'un
fichier hors droits — vous recevrez un 403 avec la raison en clair, pas une
image.

## Les appels, par tâche

**Trouver un fichier.** Une seule route, quel que soit le type de recherche :

    GET https://damdesk.com/v1/recherche?q=packshot pull hiver fond blanc

Elle cherche par les mots ET par le sens. Une référence produit
(`044_32_s1`) comme une description (`une écharpe posée sur du bois`)
fonctionnent. Chaque résultat dit par quelle voie il a été trouvé.

**Ajouter un fichier.** Vous avez presque toujours une URL, pas des octets :

    POST https://damdesk.com/v1/assets
    Content-Type: application/json

    {"url": "https://exemple.fr/photo.jpg", "dossier": "/produits/2026",
     "tags": ["packshot"], "description": "Pull col roulé, laine mérinos, fond blanc"}

Le dossier est créé s'il n'existe pas. Un fichier déjà présent au bit près
n'est PAS dupliqué : la réponse porte `doublon: true`.

**Après un import, le fichier n'est pas immédiatement complet.** Les aperçus
et les métadonnées techniques arrivent quelques secondes plus tard. Le champ
`pret` vous le dit. N'enchaînez pas sur une demande de vignette juste après
l'import : vous obtiendriez un 202.

**Décrire et ranger.**

    PATCH https://damdesk.com/v1/assets/{id}
    {"description": "…", "tags": ["hiver","laine"], "dossier": "/produits/2026"}

**Afficher une image.** Utilisez l'URL rendue dans `urls` :

    https://damdesk.com/v1/assets/{id}/contenu?w=1024

Les largeurs sont ramenées à des paliers (64, 128, 256, 384, 512, 640, 768,
1024, 1280, 1600, 2048, 2560, 3200). Demander `w=1023` sert `w=1024` :
c'est volontaire, chaque largeur distincte coûte une transformation.

## Vous êtes une IA connectée en MCP ?

Alors n'utilisez pas cette API en HTTP : le serveur MCP de https://damdesk.com/mcp
expose les mêmes capacités sous forme d'outils, avec les mêmes garde-fous, et
vous permet en plus de REGARDER les images (`voir_image`) avant d'en parler.

Outils disponibles : chercher_fichiers, lire_fiche, voir_image, televerser_fichier, decrire_fichier, verifier_droits, renseigner_droits, lister_dossiers, creer_dossier, publier_fichier, etat_photothèque, a_traiter.

## Les portées

- `assets:lire` — lire les fichiers : Lister, rechercher, voir les métadonnées et les aperçus.
- `assets:ecrire` — ajouter et modifier : Téléverser, renommer, taguer, décrire, déplacer.
- `dossiers:ecrire` — gérer les dossiers : Créer des dossiers et ranger dedans.
- `droits:lire` — consulter les droits : Licence, titulaire, échéance, crédit obligatoire.
- `droits:ecrire` — renseigner les droits : Créer et modifier une fiche de droits.
- `original:lire` — télécharger l’original : Le master, pas seulement une version redimensionnée. À réserver aux outils de production.
- `publication:ecrire` — publier sur le web : Rendre un fichier accessible SANS COMPTE à une adresse publique.
- `assets:supprimer` — mettre à la corbeille : Récupérable 30 jours. Aucune clé ne peut purger définitivement.

## Les webhooks

Le DAM peut appeler votre serveur quand quelque chose change, plutôt que de
vous faire interroger l'API en boucle :

- `asset.pret` — Aperçus générés, métadonnées extraites : le fichier est utilisable.
- `asset.publie` — Un fichier vient d’être rendu public à une adresse stable.
- `asset.supprime` — Un fichier est parti à la corbeille — à retirer de vos pages.
- `droit.expire` — La licence d’un fichier a expiré. À dépublier, ou à renouveler.

Chaque appel est signé : `X-DAMDesk-Signature: sha256=HMAC(secret, "horodatage.corps")`.

## Quand ça ne marche pas

Les erreurs portent toujours trois champs :

    {"erreur": {"code": "dossier_introuvable",
                "message": "Aucun dossier « /produit » accessible avec cette clé.",
                "que_faire": "Listez les dossiers disponibles avec GET /v1/dossiers."}}

Suivez `que_faire` plutôt que de réessayer à l'identique.

## Spécification complète

https://damdesk.com/v1/openapi.json