Requête exemple
Réponse exemple
Ajoute un élément (item) dans un coffre existant. Un élément peut être de trois types : un transfert Coffrify déjà créé (transfer), un lien externe (external_url) ou un bloc de contenu en Markdown (markdown). Comportement notable : la position est attribuée automatiquement si vous ne la fournissez pas. Le handler compte les éléments existants dans la même section (ou à la racine du coffre si section_id est null) et place le nouvel élément à la fin. Le coffre désigné par {id} doit appartenir au workspace de la clé API, et pour un élément de type transfer, le transfert référencé doit lui aussi appartenir au même workspace, sinon la requête est rejetée.
Authentification
Requiert une clé API valide envoyée via Authorization: Bearer cof_live_... (ou cof_test_...). Le scope requis est transfers:write. Les clés restreintes (cof_rk_...) et les jetons MCP (cof_mcp_...) sont acceptés tant qu'ils portent un scope satisfaisant ce besoin (le * ou un scope plus large couvre transfers:write).
Corps de la requête
Le corps doit être un objet JSON. Le champ kind est toujours obligatoire ; les autres champs requis dépendent de la valeur de kind.
| Champ | Type | Requis | Description |
|---|---|---|---|
| kind | string | Oui | Type d'élément. Une des valeurs : transfer, external_url, markdown. |
| transfer_id | string | Conditionnel | ID du transfert à rattacher. Obligatoire si kind=transfer. Le transfert doit appartenir au même workspace, sinon erreur 400. |
| external_url | string | Conditionnel | URL externe à afficher. Obligatoire si kind=external_url. |
| markdown_content | string | Conditionnel | Contenu Markdown du bloc. Obligatoire si kind=markdown. |
| section_id | string | Non | ID de la section du coffre où placer l'élément. Si fourni, la section doit appartenir au même coffre, sinon erreur 400. Par défaut null (racine du coffre). |
| position | number | Non | Position de tri dans la section. Si absent (ou falsy), le handler l'attribue automatiquement à la fin (nombre d'éléments existants dans la section). |
| is_visible | boolean | Non | Visibilité de l'élément. true par défaut ; seul false masque l'élément. |
| custom_title | string | Non | Titre personnalisé. Trimé ; une chaîne vide devient null. |
| custom_description | string | Non | Description personnalisée. Trimée ; une chaîne vide devient null. |
| thumbnail_url | string | Non | URL d'une vignette personnalisée. Trimée ; une chaîne vide devient null. |
Réponse
En cas de succès, renvoie HTTP 201 avec l'élément créé. La réponse contient l'id de l'élément, le coffre_id, la section_id, le kind, le champ spécifique au type (transfer_id, external_url ou markdown_content), les champs personnalisés (custom_title, custom_description, thumbnail_url), la position attribuée, is_visible et created_at. Si l'élément est de type transfer, l'objet imbriqué coffrify_transfers est inclus avec les métadonnées du transfert (id, short_code, transfer_title, status, expires_at, total_size_bytes). La réponse porte aussi les en-têtes standard X-Request-Id, X-Coffrify-Api-Version et les en-têtes de quota X-RateLimit-*.
Erreurs
| Code HTTP | Code erreur | Quand | Comment résoudre |
|---|---|---|---|
| 400 | validation_error | Corps non-objet, kind absent ou invalide, champ requis manquant pour le type, transfert hors workspace, ou section hors coffre. | Vérifiez que kind vaut transfer/external_url/markdown et que le champ correspondant (transfer_id/external_url/markdown_content) est bien fourni et valide pour ce workspace/coffre. |
| 401 | missing_api_key | En-tête Authorization absent. | Ajoutez l'en-tête Authorization: Bearer cof_live_.... |
| 401 | invalid_api_key | Préfixe de clé non reconnu ou clé invalide. | Utilisez une clé valide commençant par cof_live_, cof_test_, cof_rk_... ou cof_mcp_.... |
| 403 | scope_missing | La clé n'a pas le scope transfers:write. | Régénérez ou utilisez une clé portant le scope transfers:write (ou un scope plus large). |
| 404 | not_found | Le coffre {id} n'existe pas ou n'appartient pas au workspace. | Vérifiez l'id du coffre et qu'il appartient bien au workspace de la clé. |
| 429 | rate_limited | Quota par minute du workspace dépassé sur les endpoints d'écriture. | Respectez l'en-tête Retry-After et réessayez après la fenêtre indiquée par X-RateLimit-Reset. |
| 500 | internal_error | Erreur d'insertion en base. | Réessayez ; si l'erreur persiste, contactez le support avec le request_id renvoyé. |
Voir aussi
/v1/coffres/{id}/itemsListe les éléments d'un coffre, triés par (section_id, position)./v1/coffres/{id}/itemsMet à jour un élément existant (passez item_id dans le corps : titre, position, visibilité, section)./v1/coffres/{id}/itemsSupprime un élément d'un coffre (passez item_id dans le corps).