API docs by Redocly

Hubdoc API (1.0.0)

Download OpenAPI specification:

API Support: support@sinoia.fr

API de la GED Hubdoc : workspaces, dossiers, documents, éditique (Markdown/Typst), uploads, annuaire (users, contacts, groupes) et permissions.

Authentification

Toutes les requêtes exigent un token Bearer OAuth2 (ou PAT) avec le scope adapté au verbe HTTP : read pour les GET, write pour les mutations. L'obtention des tokens (flows OAuth2, device flow CLI, token exchange Edifice, PAT) est documentée sur la page Authentification.

Workspaces

Workspace management

Lister les espaces de travail

Récupérer la liste de tous les espaces de travail

Authorizations:
OAuth2PasswordOAuth2AuthCode

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Créer un espace de travail

Créer un nouvel espace de travail

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
label
string

Libellé de l'espace de travail

description
string

Description de l'espace de travail

classification_plan_id
string <uuid>

Identifiant du plan de classement associé

classification_plan_csv
string

Données CSV du plan de classement

classification_plan_label
string

Libellé du plan de classement

domain_id
string <uuid>

Identifiant du domaine associé

object
metadata_user
object

Métadonnées définies par l'utilisateur

Responses

Request samples

Content type
application/json
{
  • "label": "Project Alpha",
  • "description": "Main project workspace",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "classification_plan_csv": "string",
  • "classification_plan_label": "Standard Plan",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "settings": {
    },
  • "metadata_user": { }
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "label": "Project Alpha",
  • "description": "Main project workspace",
  • "external_id": "ext-workspace-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "classification_plan_label": "Standard Plan",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "completion_percentage": 75.5,
  • "settings": {
    },
  • "metadata_user": { },
  • "user": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Récupérer un espace de travail

Récupérer un espace de travail spécifique par identifiant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "label": "Project Alpha",
  • "description": "Main project workspace",
  • "external_id": "ext-workspace-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "classification_plan_label": "Standard Plan",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "completion_percentage": 75.5,
  • "settings": {
    },
  • "metadata_user": { },
  • "user": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Mettre à jour un espace de travail

Mettre à jour un espace de travail existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
label
string

Libellé de l'espace de travail

description
string

Description de l'espace de travail

classification_plan_id
string <uuid>

Identifiant du plan de classement associé

classification_plan_csv
string

Données CSV du plan de classement

classification_plan_label
string

Libellé du plan de classement

domain_id
string <uuid>

Identifiant du domaine associé

object
metadata_user
object

Métadonnées définies par l'utilisateur

Responses

Request samples

Content type
application/json
{
  • "label": "Project Alpha",
  • "description": "Main project workspace",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "classification_plan_csv": "string",
  • "classification_plan_label": "Standard Plan",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "settings": {
    },
  • "metadata_user": { }
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "label": "Project Alpha",
  • "description": "Main project workspace",
  • "external_id": "ext-workspace-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "classification_plan_label": "Standard Plan",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "completion_percentage": 75.5,
  • "settings": {
    },
  • "metadata_user": { },
  • "user": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Supprimer un espace de travail

Supprimer un espace de travail existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Folders

Folder management

Lister les dossiers

Récupère une liste de dossiers selon les paramètres de filtrage fournis.

Filtrage par contexte :

  • Sans paramètres : tous les dossiers accessibles à l'utilisateur
  • workspace_id : dossiers d'un workspace spécifique
  • documents_folder_id : sous-dossiers d'un dossier parent spécifique

Filtrage avancé avec Ransack :

  • Utilisez le paramètre q pour des recherches avancées
  • Exemple : q[name_cont]=admin pour chercher les dossiers contenant "admin"
Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
workspace_id
string <uuid>

ID du workspace pour filtrer les dossiers

documents_folder_id
string <uuid>

ID du dossier parent pour filtrer les sous-dossiers

sort
string
Default: "updated_at"

Champ de tri (name, updated_at, created_at, etc.)

direction
string
Default: "desc"
Enum: "asc" "desc"

Direction du tri

per_page
integer [ 1 .. 100 ]
Default: 20

Nombre d'éléments par page

page
integer >= 1
Default: 1

Numéro de page

object

Filtres Ransack pour recherche avancée. Exemples :

  • q[name_cont]=projet : nom contenant "projet"
  • q[description_present]=true : avec description
  • q[color_eq]=#FF0000 : couleur exacte en hexadecimal

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Créer un dossier

Créer un nouveau dossier

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
name
string

Nom du dossier

description
string

Description du dossier

color
string

Couleur du dossier

icon
string

Icône du dossier

documents_folder_id
string <uuid>

Identifiant du dossier parent

workspace_id
string <uuid>

Identifiant de l'espace de travail associé

Responses

Request samples

Content type
application/json
{
  • "name": "Documents",
  • "description": "Main documents folder",
  • "color": "#e74c3c",
  • "icon": "folder-open",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "Documents",
  • "description": "Main documents folder",
  • "color": "#e74c3c",
  • "icon": "folder-open",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "external_id": "ext-folder-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed891",
  • "workspace": {
    },
  • "parent": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Récupérer un dossier avec ses éléments

Récupérer un dossier spécifique par identifiant avec son contenu (sous-dossiers et fichiers)

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "Documents",
  • "description": "Main documents folder",
  • "color": "#e74c3c",
  • "icon": "folder-open",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "external_id": "ext-folder-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed891",
  • "workspace": {
    },
  • "parent": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z",
  • "items": [
    ]
}

Mettre à jour un dossier

Mettre à jour un dossier existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
name
string

Nom du dossier

description
string

Description du dossier

color
string

Couleur du dossier

icon
string

Icône du dossier

documents_folder_id
string <uuid>

Identifiant du dossier parent

workspace_id
string <uuid>

Identifiant de l'espace de travail associé

Responses

Request samples

Content type
application/json
{
  • "name": "Documents",
  • "description": "Main documents folder",
  • "color": "#e74c3c",
  • "icon": "folder-open",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "Documents",
  • "description": "Main documents folder",
  • "color": "#e74c3c",
  • "icon": "folder-open",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "external_id": "ext-folder-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed891",
  • "workspace": {
    },
  • "parent": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Supprimer un dossier

Supprimer un dossier existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Documents

Document management

Lister les documents

Récupère une liste de documents selon les paramètres de filtrage fournis.

Filtrage par contexte :

  • Sans paramètres : tous les documents accessibles à l'utilisateur
  • workspace_id : documents d'un workspace spécifique
  • documents_folder_id : documents d'un dossier spécifique

Filtrage avancé avec Ransack :

  • Utilisez le paramètre q pour des recherches avancées
  • Exemple : q[name_cont]=rapport pour chercher les documents contenant "rapport"
Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
workspace_id
string <uuid>

ID du workspace pour filtrer les documents

documents_folder_id
string <uuid>

ID du dossier pour filtrer les documents

sort
string
Default: "updated_at"

Champ de tri (name, updated_at, created_at, etc.)

direction
string
Default: "desc"
Enum: "asc" "desc"

Direction du tri

per_page
integer [ 1 .. 100 ]
Default: 20

Nombre d'éléments par page

page
integer >= 1
Default: 1

Numéro de page

object

Filtres Ransack pour recherche avancée. Exemples :

  • q[name_cont]=test : nom contenant "test"
  • q[description_present]=true : avec description

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Créer un document

Créer un document en uploadant un fichier (classique ou chunked).

Deux modes d'upload :

  • Mode classique : Upload direct d'un fichier via uploaded_file
  • Mode chunked : Référence à un upload chunked complété via chunked_upload_id

Deux scénarios :

  • Sans bulk_upload_id : Crée automatiquement un BulkUpload pour traçabilité
  • Avec bulk_upload_id : Attache le fichier à un BulkUpload existant (cas hubdoc-tools)

Mode fusion (bulk_upload avec merge_to_pdf) : le fichier est stagé (réponse 202 Accepted, aucun document individuel créé) à sa position (obligatoire, unique, à partir de 0). Quand total_files sources ont été reçues, elles sont fusionnées en un seul document PDF dans l'ordre des positions ; son ID est exposé par GET /bulk_uploads/:id (merged_document_id). Formats acceptés : PDF, JPEG, PNG.

Fonctionnalités :

  • Classification automatique optionnelle
  • Métadonnées utilisateur personnalisées
  • Source automatique basée sur l'application OAuth
Authorizations:
OAuth2PasswordOAuth2AuthCode
Request Body schema:
required
bulk_upload_id
string <uuid>

ID d'un BulkUpload existant (optionnel, pour uploads groupés)

workspace_id
string <uuid>

ID du workspace

documents_folder_id
string <uuid>

ID du dossier parent

domain_id
string <uuid>

ID du domaine

document_type_id
string <uuid>

ID du type de document

auto_classify
boolean
Default: false

Active la classification automatique des documents

metadata_user
object

Métadonnées utilisateur personnalisées

uploaded_file
string <binary>

Fichier à uploader (soit uploaded_file, soit chunked_upload_id requis)

position
integer >= 0

Position du fichier dans le PDF fusionné (requis si le BulkUpload est en mode merge_to_pdf)

pages
string

Réservé (sélection de plages de pages, non implémenté — envoyer null)

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "document.pdf",
  • "description": "Important document",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed889",
  • "document_type_id": "019951a3-01b7-7eb9-88bb-f872a01ed890",
  • "external_id": "ext-doc-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed891",
  • "byte_size": 342502,
  • "content_type": "application/pdf",
  • "metadata_user": { },
  • "workspace": {
    },
  • "folder": {
    },
  • "domain": {
    },
  • "document_type": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z",
  • "bulk_upload_id": "0fa9eaf7-c3d9-40df-8b1c-75e752c9eaa3"
}

Récupérer un document

Récupérer un document spécifique par identifiant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "document.pdf",
  • "description": "Important document",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed889",
  • "document_type_id": "019951a3-01b7-7eb9-88bb-f872a01ed890",
  • "external_id": "ext-doc-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed891",
  • "byte_size": 342502,
  • "content_type": "application/pdf",
  • "metadata_user": { },
  • "workspace": {
    },
  • "folder": {
    },
  • "domain": {
    },
  • "document_type": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Mettre à jour un document

Mettre à jour un document existant.

Deux modes :

  • application/json : Mise à jour des métadonnées uniquement (name, description, etc.)
  • multipart/form-data : Remplacement du fichier via uploaded_file
Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Request Body schema:
required
name
string

Nom du fichier

description
string

Description du fichier

uploaded_file
string <binary>

Fichier à télécharger

documents_folder_id
string <uuid>

Identifiant du dossier parent

workspace_id
string <uuid>

Identifiant de l'espace de travail associé

domain_id
string <uuid>

Identifiant du domaine associé

document_type_id
string <uuid>

Identifiant du type de document associé

metadata_user
object

Métadonnées définies par l'utilisateur

auto_classify
boolean
Default: false

Active la classification automatique du document

Responses

Request samples

Content type
{
  • "name": "document.pdf",
  • "description": "Important document",
  • "uploaded_file": "string",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed889",
  • "document_type_id": "019951a3-01b7-7eb9-88bb-f872a01ed890",
  • "metadata_user": { },
  • "auto_classify": true
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "document.pdf",
  • "description": "Important document",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed889",
  • "document_type_id": "019951a3-01b7-7eb9-88bb-f872a01ed890",
  • "external_id": "ext-doc-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed891",
  • "byte_size": 342502,
  • "content_type": "application/pdf",
  • "metadata_user": { },
  • "workspace": {
    },
  • "folder": {
    },
  • "domain": {
    },
  • "document_type": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Supprimer un document

Supprimer un document existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Créer une nouvelle version d'un document

Crée une nouvelle version du document : le contenu courant est d'abord archivé comme version (historique), puis remplacé par le fichier uploadé. L'identifiant du document reste inchangé.

À utiliser lorsqu'un livrable déjà présent doit être mis à jour sans créer de doublon ni casser les liens existants (ex. resync d'un artefact modifié par un agent Hubdoc/Synapse).

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Request Body schema:
required
uploaded_file
string <binary>

Nouveau contenu du document (soit uploaded_file, soit chunked_upload_id requis)

chunked_upload_id
string <uuid>

Référence à un upload chunked complété (alternative à uploaded_file)

comment
string

Commentaire optionnel associé à la version créée

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "document.pdf",
  • "description": "Important document",
  • "documents_folder_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "workspace_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "domain_id": "019951a3-01b7-7eb9-88bb-f872a01ed889",
  • "document_type_id": "019951a3-01b7-7eb9-88bb-f872a01ed890",
  • "external_id": "ext-doc-12345",
  • "classification_plan_id": "019951a3-01b7-7eb9-88bb-f872a01ed891",
  • "byte_size": 342502,
  • "content_type": "application/pdf",
  • "metadata_user": { },
  • "workspace": {
    },
  • "folder": {
    },
  • "domain": {
    },
  • "document_type": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Lister les polices Typst disponibles

Catalogue des polices effectivement résolvables par le compilateur Typst (mêmes chemins que la compilation des ComposedDocument). Permet de découvrir les font_family valides avant de configurer page_settings.font_family.

Réponse cachée 1h (les polices ne changent qu'au déploiement / à l'installation de paquets).

Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
include_system
boolean
Default: true

Inclure les polices système (/usr/share/fonts) en plus des polices embarquées.

with_variants
boolean
Default: true

Inclure la liste des variantes (graisses/styles) par famille.

Responses

Response samples

Content type
application/json
{
  • "fonts": [
    ],
  • "total": 238,
  • "font_paths": [
    ]
}

Composed Documents

Composed Documents — éditique Markdown/Typst. Permet de créer des documents à partir d'un template, gérer les parts (sections), et compiler en PDF via le pipeline Typst.

Lister les documents composés

Liste les ComposedDocument accessibles à l'utilisateur (scopés par ComposedDocumentPolicy::Scope).

Filtres optionnels :

  • workspace_id : workspace propriétaire
  • folder_id : dossier propriétaire
  • status : draft / in_progress / ready / exported
Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
workspace_id
string <uuid>
folder_id
string <uuid>
status
string
Enum: "draft" "in_progress" "ready" "exported"
per_page
integer [ 1 .. 100 ]
Default: 20
page
integer >= 1
Default: 1

Responses

Response samples

Content type
application/json
{
  • "composed_documents": [
    ]
}

Créer un document composé à partir d'un template

Instancie un ComposedDocument depuis un DocumentTemplate identifié par sa key. Le typst_source, variables_schema et default_parts sont hérités du template ; les variables du body remplissent les placeholders.

Pipeline d'interactor : Documents::ComposedDocuments::CreateFromTemplate.

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
template_key
required
string

(Création seulement) Slug d'un DocumentTemplate. Le composed document hérite du typst_source, variables_schema et default_parts du template. La création utilise l'interactor Documents::ComposedDocuments::CreateFromTemplate.

name
string

Nom du document (par défaut, nom du template)

description
string
object

Valeurs des variables du template

object
typst_source
string

(Update) Source Typst complète. Combiné à assembly_mode: pure_typst pour piloter le rendu sans injection (#463). Côté CLI : set-typst.

assembly_mode
string
Enum: "composed" "pure_typst"

(Update) Bascule le mode d'assemblage (#463). Un mode invalide est rejeté en 422.

workspace_id
string <uuid>
folder_id
string <uuid>
object

Responses

Request samples

Content type
application/json
{
  • "template_key": "facture-edf",
  • "name": "Facture Sinoia 2026-05",
  • "description": "string",
  • "variables": {
    },
  • "page_settings": { },
  • "typst_source": "string",
  • "assembly_mode": "composed",
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  • "folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
  • "metadata_user": { }
}

Response samples

Content type
application/json
{
  • "composed_document": {
    }
}

Récupérer un document composé

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "composed_document": {
    }
}

Modifier un document composé

Met à jour les attributs modifiables : name, description, variables, page_settings, metadata_user. Le typst_source n'est pas modifié directement par cette route — pour modifier le contenu, utiliser les endpoints /parts.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
template_key
string

(Création seulement) Slug d'un DocumentTemplate. Le composed document hérite du typst_source, variables_schema et default_parts du template. La création utilise l'interactor Documents::ComposedDocuments::CreateFromTemplate.

name
string

Nom du document (par défaut, nom du template)

description
string
object

Valeurs des variables du template

object
typst_source
string

(Update) Source Typst complète. Combiné à assembly_mode: pure_typst pour piloter le rendu sans injection (#463). Côté CLI : set-typst.

assembly_mode
string
Enum: "composed" "pure_typst"

(Update) Bascule le mode d'assemblage (#463). Un mode invalide est rejeté en 422.

workspace_id
string <uuid>
folder_id
string <uuid>
object

Responses

Request samples

Content type
application/json
{
  • "template_key": "facture-edf",
  • "name": "Facture Sinoia 2026-05",
  • "description": "string",
  • "variables": {
    },
  • "page_settings": { },
  • "typst_source": "string",
  • "assembly_mode": "composed",
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  • "folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
  • "metadata_user": { }
}

Response samples

Content type
application/json
{
  • "composed_document": {
    }
}

Supprimer un document composé

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Compiler le document composé en PDF

Déclenche le pipeline Documents::ComposedDocuments::AssembleAndCompile :

  1. Assemble les parts (markdown converti, typst concaténé)
  2. Compile via Documents::TypstCompiler → PDF
  3. Attache le PDF au Documents::File du composed_document
  4. Passe le status à exported
  5. Republie pour ré-indexation search

Synchrone : la réponse n'arrive qu'une fois le PDF compilé et attaché — pas de polling nécessaire côté client.

Retourne une structure PLATE dédiée au résultat d'export (le PDF est en tête via pdf_file_id). Le détail du composé reste accessible via GET /composed_documents/:id.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

query Parameters
include_draft
boolean
Default: false

Inclure les parts en statut draft dans le rendu (défaut false).

Responses

Response samples

Content type
application/json
{}

Lister les parts d'un document composé

Retourne toutes les Documents::Part du composed_document, ordonnées par position.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "parts": [
    ]
}

Récupérer une part

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>

ID du composed_document parent

part_id
required
string <uuid>

ID de la part

Responses

Response samples

Content type
application/json
{
  • "part": {
    }
}

Modifier une part

Met à jour les attributs modifiables d'une part : title, content, content_format, position, status, alignment, page_break, etc.

Les transitions de status sont validées par Documents::Part::VALID_TRANSITIONS.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>

ID du composed_document parent

part_id
required
string <uuid>

ID de la part

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
title
string
content
string
content_format
string
Enum: "typst" "markdown"
content_source
string
Enum: "human" "agent" "template"
part_type
string
Enum: "content" "header" "footer" "signature" "appendix"
position
integer
status
string
Enum: "draft" "editing" "ready" "validated" "locked"
alignment
string
Enum: "left" "center" "right"
bsize
integer [ 1 .. 12 ]
page_break
boolean
row_group
integer
key
string
instructions
string
assignee_id
string <uuid>
assignee_type
string
object

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "content": "string",
  • "content_format": "typst",
  • "content_source": "human",
  • "part_type": "content",
  • "position": 0,
  • "status": "draft",
  • "alignment": "left",
  • "bsize": 1,
  • "page_break": true,
  • "row_group": 0,
  • "key": "string",
  • "instructions": "string",
  • "assignee_id": "e209ca2d-190b-4818-b659-67d4ef4f1ce8",
  • "assignee_type": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "part": {
    }
}

Supprimer une part

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>

ID du composed_document parent

part_id
required
string <uuid>

ID de la part

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Réordonner les parts d'un document composé

Met à jour les positions de toutes les parts en un seul appel. Le body est un array [{ id: uuid, position: int }, ...].

Toutes les parts du document doivent être incluses (sinon les omises restent à leur position actuelle, mais on recommande de toujours envoyer la liste complète).

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
required
Array of objects

Liste {id, position} pour chaque part à repositionner

Responses

Request samples

Content type
application/json
{
  • "parts": [
    ]
}

Response samples

Content type
application/json
{
  • "parts": [
    ]
}

Document Templates

Document Templates — modèles Typst/Markdown réutilisables. Read-only pour tous les users, CRUD réservé aux admins.

Lister les templates de document actifs

Retourne tous les DocumentTemplate actifs, triés par nom.

Templates = modèles de documents Typst/Markdown servant de base à la création de ComposedDocument. Read-only pour tout user authentifié, CRUD réservé aux admins.

Authorizations:
OAuth2PasswordOAuth2AuthCode

Responses

Response samples

Content type
application/json
{
  • "templates": [
    ]
}

Créer un nouveau template (admin only)

Crée un DocumentTemplate. Réservé aux administrateurs (Pundit DocumentTemplatePolicy#create? = administrator?).

Le typst_source et la key sont obligatoires. key doit être unique.

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
key
string

Slug unique du template

name
string

Nom affiché du template

description
string

Description longue

category
string

Catégorie fonctionnelle

locale
string
Default: "fr"
typst_source
string

Source Typst du template (placeholders {{var}} supportés)

object

JSON Schema simplifié décrivant les variables attendues

Array of objects

Parts par défaut du template (JSONB array d'objets)

object

Configuration page

active
boolean
Default: true

Le template est-il actif

Responses

Request samples

Content type
application/json
{
  • "key": "facture-edf",
  • "name": "Facture EDF",
  • "description": "string",
  • "category": "billing",
  • "locale": "fr",
  • "typst_source": "string",
  • "variables_schema": { },
  • "default_parts": [
    ],
  • "page_settings": { },
  • "active": true
}

Response samples

Content type
application/json
{
  • "template": {
    }
}

Récupérer un template

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "template": {
    }
}

Modifier un template (admin only)

Met à jour les attributs d'un template. Seuls les champs présents dans le body sont touchés. Réservé aux administrateurs.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
key
string

Slug unique du template

name
string

Nom affiché du template

description
string

Description longue

category
string

Catégorie fonctionnelle

locale
string
Default: "fr"
typst_source
string

Source Typst du template (placeholders {{var}} supportés)

object

JSON Schema simplifié décrivant les variables attendues

Array of objects

Parts par défaut du template (JSONB array d'objets)

object

Configuration page

active
boolean
Default: true

Le template est-il actif

Responses

Request samples

Content type
application/json
{
  • "key": "facture-edf",
  • "name": "Facture EDF",
  • "description": "string",
  • "category": "billing",
  • "locale": "fr",
  • "typst_source": "string",
  • "variables_schema": { },
  • "default_parts": [
    ],
  • "page_settings": { },
  • "active": true
}

Response samples

Content type
application/json
{
  • "template": {
    }
}

Supprimer un template (admin only)

Supprime un template. Refuse si des composed_documents y sont rattachés (422). Passer ?force=true pour nullifier les références au lieu de bloquer.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

query Parameters
force
boolean
Default: false

Nullifier les composed_documents rattachés au lieu de bloquer

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

BulkUploads

Bulk upload operations

Créer un BulkUpload

Créer un BulkUpload pour regrouper plusieurs fichiers uploadés séparément.

Workflow typique :

  1. Créer un BulkUpload avec le nombre total de fichiers
  2. Uploader chaque fichier via POST /api/v1/documents/documents en passant le bulk_upload_id
  3. Récupérer le statut final via GET /api/v1/documents/bulk_uploads/:id

Cas d'usage :

  • Import en masse depuis hubdoc-tools
  • Upload parallélisé de gros volumes
  • Traçabilité d'un lot d'uploads

Mode fusion PDF (merge_to_pdf: true + merged_file_name) : les fichiers du lot ne créent pas de documents individuels ; chacun est envoyé avec une position explicite, puis toutes les sources sont fusionnées en un seul document PDF dans l'ordre des positions dès que total_files sources ont été reçues. Suivre GET /bulk_uploads/:id jusqu'au statut completed pour récupérer merged_document_id. Formats acceptés : PDF, JPEG, PNG (les images deviennent une page A4).

Authorizations:
OAuth2PasswordOAuth2AuthCode
Request Body schema: application/json
required
total_files
required
integer [ 1 .. 100 ]

Nombre total de fichiers qui seront uploadés

documents_folder_id
string <uuid>

ID du dossier de destination

workspace_id
string <uuid>

ID du workspace

auto_classify
boolean
Default: false

Activer la classification automatique des documents

source
string

Source de l'upload (sera auto-détecté depuis OAuth si non fourni)

merge_to_pdf
boolean
Default: false

Fusionner toutes les sources du lot en un seul document PDF. Chaque fichier doit alors être envoyé avec une position explicite ; la fusion démarre quand total_files sources ont été reçues. Formats acceptés : PDF, JPEG, PNG (les images deviennent une page).

merged_file_name
string

Nom du document PDF fusionné (requis si merge_to_pdf est vrai, l'extension .pdf est ajoutée si absente)

Responses

Request samples

Content type
application/json
Example
{
  • "total_files": 50,
  • "source": "hubdoc-tools"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "source": "string",
  • "total_files": 0,
  • "processed_files": 0,
  • "successful_files": 0,
  • "failed_files": 0,
  • "progress": 100,
  • "auto_classify": true,
  • "merge_to_pdf": true,
  • "merged_file_name": "string",
  • "received_files": 0,
  • "merged_document_id": "2627a545-7148-455e-bfe7-7ae47aa3b9f9",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Récupérer un BulkUpload

Récupère les informations et le statut d'un BulkUpload.

Utilisation :

  • Suivre la progression d'un import en masse
  • Vérifier le statut final après tous les uploads
  • Obtenir le nombre de fichiers en succès/échec
Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>

ID du BulkUpload

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "source": "string",
  • "total_files": 0,
  • "processed_files": 0,
  • "successful_files": 0,
  • "failed_files": 0,
  • "progress": 100,
  • "auto_classify": true,
  • "merge_to_pdf": true,
  • "merged_file_name": "string",
  • "received_files": 0,
  • "merged_document_id": "2627a545-7148-455e-bfe7-7ae47aa3b9f9",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

ChunkedUploads

Chunked upload operations

Initialiser une session d'upload par chunks

Crée une session d'upload pour un fichier volumineux qui sera uploadé par morceaux (chunks).

Workflow typique :

  1. Initialiser la session avec ce endpoint (retourne un upload_id)
  2. Uploader chaque chunk via PATCH /api/v1/documents/chunked_uploads/{upload_id}/chunks/{chunk_number}
  3. Finaliser l'upload via POST /api/v1/documents/chunked_uploads/{upload_id}/complete
  4. Créer le document final via POST /api/v1/documents/documents avec le chunked_upload_id

Limites :

  • Taille max de fichier : 5 GB
  • Taille de chunk recommandée : 5 MB
  • Durée de vie de la session : 24 heures

Cas d'usage :

  • Upload de fichiers > 10 MB
  • Upload avec suivi de progression granulaire
  • Upload avec reprise en cas d'interruption
Authorizations:
OAuth2PasswordOAuth2AuthCode
Request Body schema: application/json
required
filename
required
string

Nom du fichier à uploader

file_size
required
integer <int64> [ 1 .. 5368709120 ]

Taille totale du fichier en octets

content_type
required
string

Type MIME du fichier

chunk_size
integer [ 1048576 .. 104857600 ]
Default: 5242880

Taille de chaque chunk en octets (optionnel, défaut 5MB)

workspace_id
string or null <uuid>

ID du workspace de destination (optionnel)

documents_folder_id
string or null <uuid>

ID du dossier de destination (optionnel)

object or null

Métadonnées additionnelles (optionnel)

Responses

Request samples

Content type
application/json
Example
{
  • "filename": "document.pdf",
  • "file_size": 52428800,
  • "content_type": "application/pdf",
  • "chunk_size": 5242880
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Uploader un chunk

Upload un chunk spécifique d'un fichier dans une session d'upload par chunks.

Important :

  • Les chunks sont numérotés à partir de 1
  • Le body doit contenir les données binaires brutes du chunk
  • Content-Type doit être application/octet-stream
  • Les chunks peuvent être uploadés dans n'importe quel ordre
  • Les chunks déjà uploadés retournent une réponse idempotente (pas de re-upload)

Retry :

  • En cas d'échec, le client peut retry le même chunk
  • L'API gère l'idempotence automatiquement

Progression :

  • La réponse inclut la progression globale
  • Utilisez GET /api/v1/documents/chunked_uploads/{id}/status pour un statut détaillé
Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string
Example: a1b2c3d4e5f6

Identifiant unique de la session d'upload (upload_id)

chunk_number
required
integer >= 1
Example: 5

Numéro du chunk à uploader (1-indexed)

Request Body schema: application/octet-stream
required

Données binaires du chunk

string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Finaliser l'upload par chunks

Finalise une session d'upload par chunks en assemblant tous les chunks.

Prérequis :

  • Tous les chunks doivent avoir été uploadés
  • La session ne doit pas être expirée

Processus :

  1. Vérifie que tous les chunks sont présents
  2. Assemble les chunks dans le storage (MinIO/S3)
  3. Vérifie le checksum si fourni (recommandé)
  4. Marque la session comme "completed"
  5. Retourne l'object_key pour référence future

Après finalisation :

  • Utilisez l'upload_id pour créer le document final via POST /api/v1/documents/documents
  • Le fichier assemblé est disponible dans le storage
Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string
Example: a1b2c3d4e5f6

Identifiant unique de la session d'upload (upload_id)

Request Body schema: application/json
optional
checksum
string or null

Checksum MD5 du fichier complet en base64 (optionnel mais recommandé)

Responses

Request samples

Content type
application/json
{
  • "checksum": "1B2M2Y8AsgTpgAmY7PhCfg=="
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Obtenir le statut d'un upload

Récupère le statut actuel d'une session d'upload par chunks.

Informations retournées :

  • Statut actuel (pending, processing, completed, failed, cancelled, expired)
  • Progression en pourcentage
  • Nombre de chunks uploadés vs total
  • Date d'expiration
  • Indicateur d'expiration

Cas d'usage :

  • Suivi de progression pendant l'upload
  • Vérification avant de finaliser
  • Reprise après interruption
  • Monitoring d'uploads parallèles
Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string
Example: a1b2c3d4e5f6

Identifiant unique de la session d'upload (upload_id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Annuler un upload

Annule une session d'upload par chunks en cours.

Actions effectuées :

  • Annule le multipart upload sur le storage
  • Supprime tous les chunks uploadés
  • Marque la session comme "cancelled"

Restrictions :

  • Ne peut pas annuler un upload déjà complété
  • Les sessions expirées sont automatiquement nettoyées

Cas d'usage :

  • Annulation volontaire de l'utilisateur
  • Erreur détectée côté client
  • Upload obsolète ou erroné
Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string
Example: a1b2c3d4e5f6

Identifiant unique de la session d'upload (upload_id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Users

User management

Lister les utilisateurs

Récupère une liste d'utilisateurs selon les paramètres de filtrage fournis.

Filtrage avancé avec Ransack :

  • Utilisez le paramètre q pour des recherches avancées
  • Exemple : q[role_eq]=admin pour chercher les utilisateurs administrateurs
Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
sort
string
Default: "updated_at"

Champ de tri (email_address, first_name, last_name, role, created_at, updated_at, etc.)

direction
string
Default: "desc"
Enum: "asc" "desc"

Direction du tri

per_page
integer [ 1 .. 100 ]
Default: 20

Nombre d'éléments par page

page
integer >= 1
Default: 1

Numéro de page

object

Filtres Ransack pour recherche avancée. Exemples :

  • q[email_address_cont]=john : email contenant "john"
  • q[role_eq]=admin : rôle exact
  • q[first_name_or_last_name_cont]=doe : prénom ou nom contenant "doe"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Créer un utilisateur

Créer un nouvel utilisateur

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
email_address
required
string <email>

Adresse email de l'utilisateur

password
string <password> >= 6 characters

Mot de passe de l'utilisateur (minimum 6 caractères)

first_name
string <= 50 characters

Prénom de l'utilisateur

last_name
string <= 50 characters

Nom de famille de l'utilisateur

role
string
Default: "user"
Enum: "user" "manager" "admin" "super_admin"

Rôle de l'utilisateur

external_id
string or null

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "email_address": "john.doe@example.com",
  • "password": "securePassword123",
  • "first_name": "John",
  • "last_name": "Doe",
  • "role": "user",
  • "external_id": "ext-user-12345"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "email_address": "john.doe@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "display_name": "John Doe",
  • "initials": "JD",
  • "role": "user",
  • "externa_id": "ext-user-12345",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Récupérer un utilisateur

Récupérer un utilisateur spécifique par identifiant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "email_address": "john.doe@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "display_name": "John Doe",
  • "initials": "JD",
  • "role": "user",
  • "externa_id": "ext-user-12345",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Mettre à jour un utilisateur

Mettre à jour un utilisateur existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
email_address
required
string <email>

Adresse email de l'utilisateur

password
string <password> >= 6 characters

Mot de passe de l'utilisateur (minimum 6 caractères)

first_name
string <= 50 characters

Prénom de l'utilisateur

last_name
string <= 50 characters

Nom de famille de l'utilisateur

role
string
Default: "user"
Enum: "user" "manager" "admin" "super_admin"

Rôle de l'utilisateur

external_id
string or null

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "email_address": "john.doe@example.com",
  • "password": "securePassword123",
  • "first_name": "John",
  • "last_name": "Doe",
  • "role": "user",
  • "external_id": "ext-user-12345"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "email_address": "john.doe@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "display_name": "John Doe",
  • "initials": "JD",
  • "role": "user",
  • "externa_id": "ext-user-12345",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Supprimer un utilisateur

Supprimer un utilisateur existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Contacts

Contact management

Lister les contacts

Récupère une liste de contacts selon les paramètres de filtrage fournis.

Filtrage avancé avec Ransack :

  • Utilisez le paramètre q pour des recherches avancées
  • Exemple : q[email_address_cont]=example.com pour chercher les contacts avec une adresse contenant "example.com"
Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
sort
string
Default: "updated_at"

Champ de tri (email_address, first_name, last_name, created_at, updated_at, etc.)

direction
string
Default: "desc"
Enum: "asc" "desc"

Direction du tri

per_page
integer [ 1 .. 100 ]
Default: 20

Nombre d'éléments par page

page
integer >= 1
Default: 1

Numéro de page

object

Filtres Ransack pour recherche avancée. Exemples :

  • q[email_address_cont]=example.com : email contenant "example.com"
  • q[first_name_eq]=John : prénom exacte
  • q[last_name_start]=Doe : nom commençant par "Doe"
  • q[external_id_eq]=ext-123 : identifiant externe exact

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Créer un contact

Créer un nouveau contact

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
email_address
required
string <email>

Adresse email du contact

first_name
string

Prénom du contact

last_name
string

Nom du contact

external_id
string

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "email_address": "contact@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "external_id": "ext-12345"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "email_address": "contact@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "external_id": "ext-12345",
  • "display_name": "John Doe",
  • "full_name": "John Doe",
  • "type": "Contact",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Récupérer un contact

Récupérer un contact spécifique par identifiant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "email_address": "contact@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "external_id": "ext-12345",
  • "display_name": "John Doe",
  • "full_name": "John Doe",
  • "type": "Contact",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Mettre à jour un contact

Mettre à jour un contact existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
email_address
required
string <email>

Adresse email du contact

first_name
string

Prénom du contact

last_name
string

Nom du contact

external_id
string

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "email_address": "contact@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "external_id": "ext-12345"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "email_address": "contact@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "external_id": "ext-12345",
  • "display_name": "John Doe",
  • "full_name": "John Doe",
  • "type": "Contact",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Supprimer un contact

Supprimer un contact existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Groups

Group management

Lister les groupes

Récupère une liste de groupes selon les paramètres de filtrage fournis.

Filtrage avancé avec Ransack :

  • Utilisez le paramètre q pour des recherches avancées
  • Exemple : q[name_cont]=admin pour chercher les groupes contenant "admin"
Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
sort
string
Default: "updated_at"

Champ de tri (name, description, created_at, updated_at, etc.)

direction
string
Default: "desc"
Enum: "asc" "desc"

Direction du tri

per_page
integer [ 1 .. 100 ]
Default: 20

Nombre d'éléments par page

page
integer >= 1
Default: 1

Numéro de page

object

Filtres Ransack pour recherche avancée. Exemples :

  • q[name_cont]=admin : nom contenant "admin"
  • q[description_present]=true : avec description
  • q[external_id_eq]=ext-group : identifiant externe exact

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Créer un groupe

Créer un nouveau groupe

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
name
required
string

Nom du groupe

description
string

Description du groupe

external_id
string

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "name": "Administrators",
  • "description": "Group for system administrators",
  • "external_id": "ext-admin-group"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "Administrators",
  • "description": "Group for system administrators",
  • "external_id": "ext-admin-group",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Récupérer un groupe

Récupérer un groupe spécifique par identifiant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "Administrators",
  • "description": "Group for system administrators",
  • "external_id": "ext-admin-group",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Mettre à jour un groupe

Mettre à jour un groupe existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
name
required
string

Nom du groupe

description
string

Description du groupe

external_id
string

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "name": "Administrators",
  • "description": "Group for system administrators",
  • "external_id": "ext-admin-group"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "name": "Administrators",
  • "description": "Group for system administrators",
  • "external_id": "ext-admin-group",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Supprimer un groupe

Supprimer un groupe existant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Group Members

Membres d'un groupe (ajout, retrait, liste)

Lister les membres d'un groupe

Récupère la liste des membres d'un groupe spécifique. Requiert les droits administrateur.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
group_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed887

Identifiant du groupe

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Ajouter un membre à un groupe

Ajoute un utilisateur comme membre d'un groupe via son identifiant externe. L'opération est idempotente : si l'utilisateur est déjà membre, retourne le membership existant avec un statut 200. Requiert les droits administrateur.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
group_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed887

Identifiant du groupe

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
user_external_id
required
string

Identifiant externe de l'utilisateur à ajouter au groupe

role
string
Default: "member"
Enum: "member" "admin" "owner"

Rôle à attribuer au membre (par défaut "member")

Responses

Request samples

Content type
application/json
{
  • "user_external_id": "ext-user-123",
  • "role": "member"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "group_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "member_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "member_type": "User",
  • "role": "member",
  • "user_external_id": "ext-user-123",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Retirer un membre d'un groupe

Retire un membre d'un groupe par son identifiant de membership. Alternativement, le paramètre user_external_id peut être passé pour identifier le membre à retirer. Requiert les droits administrateur.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
group_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed887

Identifiant du groupe

id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant du membership

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Permissions

Permission management

Lister les permissions

Récupère une liste de permissions selon les paramètres de filtrage fournis.

Filtrage avancé avec Ransack :

  • Utilisez le paramètre q pour des recherches avancées
  • Exemple : q[level_eq]=admin pour chercher les permissions de niveau admin
Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
permissible_type
required
string
Example: permissible_type=Documents::File

Type de la ressource (ex. Documents::File, Documents::Folder, Documents::Workspace)

permissible_id
required
string <uuid>
Example: permissible_id=019951a3-01b7-7eb9-88bb-f872a01ed886

ID de la ressource

sort
string
Default: "updated_at"

Champ de tri (level, actor_type, permissible_type, created_at, updated_at, etc.)

direction
string
Default: "desc"
Enum: "asc" "desc"

Direction du tri

per_page
integer [ 1 .. 100 ]
Default: 20

Nombre d'éléments par page

page
integer >= 1
Default: 1

Numéro de page

object

Filtres Ransack pour recherche avancée. Exemples :

  • q[level_eq]=admin : niveau de permission exact
  • q[actor_type_eq]=User : type d'acteur exact
  • q[permissible_type_eq]=Documents::File : type de ressource exact
  • q[actor_id_eq]=019951a3-... : acteur spécifique
  • q[permissible_id_eq]=019951a3-... : ressource spécifique

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Créer une permission

Créer une nouvelle permission

Authorizations:
OAuth2PasswordOAuth2AuthCode
header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
level
required
string
Enum: "read" "write" "admin"

Niveau de permission (read, write, admin)

actor_id
required
string <uuid>

Identifiant de l'acteur (User, Contact, Group)

actor_type
required
string

Type d'acteur (User, Contact, Group)

permissible_id
required
string <uuid>

Identifiant de la ressource protégée

permissible_type
required
string

Type de ressource protégée (Documents::File, Documents::Folder, etc.)

external_id
string

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "level": "read",
  • "actor_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "actor_type": "User",
  • "permissible_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "permissible_type": "Documents::File",
  • "external_id": "ext-perm-12345"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "level": "read",
  • "actor_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "actor_type": "User",
  • "permissible_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "permissible_type": "Documents::File",
  • "external_id": "ext-perm-12345",
  • "actor": {
    },
  • "permissible": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Récupérer une permission

Récupérer une permission spécifique par identifiant

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "level": "read",
  • "actor_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "actor_type": "User",
  • "permissible_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "permissible_type": "Documents::File",
  • "external_id": "ext-perm-12345",
  • "actor": {
    },
  • "permissible": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Mettre à jour une permission

Mettre à jour une permission existante

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

header Parameters
Content-Type
required
string
Value: "application/json"
Example: application/json

Type de contenu de la requête

Request Body schema: application/json
required
level
required
string
Enum: "read" "write" "admin"

Niveau de permission (read, write, admin)

actor_id
required
string <uuid>

Identifiant de l'acteur (User, Contact, Group)

actor_type
required
string

Type d'acteur (User, Contact, Group)

permissible_id
required
string <uuid>

Identifiant de la ressource protégée

permissible_type
required
string

Type de ressource protégée (Documents::File, Documents::Folder, etc.)

external_id
string

Identifiant externe pour l'intégration avec des systèmes tiers

Responses

Request samples

Content type
application/json
{
  • "level": "read",
  • "actor_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "actor_type": "User",
  • "permissible_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "permissible_type": "Documents::File",
  • "external_id": "ext-perm-12345"
}

Response samples

Content type
application/json
{
  • "id": "019951a3-01b7-7eb9-88bb-f872a01ed886",
  • "level": "read",
  • "actor_id": "019951a3-01b7-7eb9-88bb-f872a01ed887",
  • "actor_type": "User",
  • "permissible_id": "019951a3-01b7-7eb9-88bb-f872a01ed888",
  • "permissible_type": "Documents::File",
  • "external_id": "ext-perm-12345",
  • "actor": {
    },
  • "permissible": {
    },
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-01-01T00:00:00Z"
}

Supprimer une permission

Supprimer une permission existante

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Public Access

Accès public — la troisième voie d'accès, à côté des ACL nominatives et des liens de partage. Rendre public, rendre privé, repropager, exclure, lever une exclusion, et lire l'état qui en résulte.

Deux modèles de propagation, délibérément différents

ACL nominatives Accès public
Mécanisme ascendance évaluée à la lecture estampillage explicite, ligne par ressource
Document ajouté après hérite immédiatement pas public tant qu'on n'a pas repropagé
Document déplacé hors du sous-arbre perd le droit concession périmée
Retrait sur une ressource impossible sans permission négative marqueur d'exclusion, transitif

La divergence est volontaire : fail-closed assumé, pour qu'aucune ressource ne soit publique sans qu'un dossier l'annonce. Elle surprend, d'où subtree.unstamped et reason dans l'état rendu.

Ce que l'accès public N'ouvre PAS

  • aucune écriture : le court-circuit est borné à la lecture, un accès public ne sert donc jamais à obtenir le droit de publier ;
  • aucune indexation : une ressource publique n'est délibérément pas cherchable ;
  • la racine d'une publication est toujours un dossier.

Lire l'état d'accès public d'un dossier

Rend l'état complet : publique ou non, la racine qui l'explique, les exclusions, et le bilan du sous-arbre — dont les ressources non estampillées, celles qu'une repropagation rendrait publiques.

Exige le droit d'écriture sur le dossier, et non de lecture : l'état énumère nommément le complément privé du sous-arbre publié. L'ouvrir en lecture rendrait un dossier public utilisable comme annuaire de ce qu'il ne publie pas.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
folder_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant du dossier

query Parameters
limit
integer [ 0 .. 500 ]
Default: 50

Borne le tableau subtree.unstamped_items. Défaut 50, maximum 500. Le décompte subtree.unstamped reste exact quelle que soit la borne.

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Publier un dossier (rendre public)

Publie le dossier comme racine publique et propage la concession sur tout son sous-arbre. Geste explicite, tracé et révocable.

C'est la porte générique du « rendre public » : elle remplace le détour par POST /api/v1/documents/folders/{id}/site, qui reste servi le temps que le CLI publié migre (hubdoc-tools#29) mais ne doit plus être employé pour ce geste.

La racine d'une publication est toujours un dossier : rendre un document isolé public n'existe pas. Les documents sont couverts par la propagation depuis un dossier.

Idempotent : republier un dossier déjà publié rend 200 et ne ressuscite aucune concession que personne n'a reprise. Publier lève l'exclusion portée par le dossier lui-même (celles de ses descendants restent).

Action à conséquence : la portée doit être annoncée à l'utilisateur avant validation, jamais après.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
folder_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant du dossier

Request Body schema: application/json
optional
propagate
boolean
Default: true

false publie la racine SANS estampiller le sous-arbre : seul le dossier devient public. Réservé aux publications en deux temps ; la propagation reste alors à faire explicitement.

Responses

Request samples

Content type
application/json
{
  • "propagate": true
}

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Dépublier un dossier (rendre privé)

Retire la racine publique. Une seule écriture : toutes les concessions du sous-arbre sont conditionnées à la présence de cette racine, elles périment donc d'un coup, sans dépropagation ni tâche de fond.

Idempotent. L'état rendu après coup n'est pas redondant : un dossier imbriqué dans un AUTRE sous-arbre publié reste public une fois dépublié, et seul l'état le dit.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
folder_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant du dossier

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Repropager l'accès public sur le sous-arbre

Réestampille tout le sous-arbre d'une racine publiée : l'existant est réestampillé, les ajouts sont couverts. Idempotent.

C'est la contrepartie assumée du fail-closed. Un document déposé dans un dossier publié n'est pas public tant que ce geste n'a pas eu lieu : subtree.unstamped le compte, ce geste le résorbe. Un agent qui régénère un site doit enchaîner régénération et repropagation.

Les ressources explicitement exclues ne sont jamais réestampillées — sans quoi l'exclusion serait illusoire dès la première régénération.

Échoue en 422 si le dossier n'est pas publié comme racine : propager n'est pas un raccourci pour publier.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
folder_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant du dossier

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Exclure un dossier de l'accès public

Pose le marqueur « jamais public ici » sur le dossier et coupe l'accès immédiatement : les concessions qu'il portait sont retirées, celles de son sous-arbre aussi.

La portée est TRANSITIVE : exclure un dossier exclut tout ce qu'il contient, aujourd'hui et demain. Elle doit être annoncée à l'utilisateur avant validation — sans quoi « jamais public ici » ne protégerait que le libellé du dossier pendant que son contenu resterait lisible par URL directe.

Le marqueur survit aux repropagations et voyage avec la ressource : un dossier exclu déplacé dans un autre sous-arbre public reste exclu. Le retirer est un geste explicite (DELETE).

Exclure un dossier qui est lui-même une racine publiée le dépublie : c'est bien le sens du geste.

Idempotent : 200 si l'exclusion existait déjà, 201 sinon.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
folder_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant du dossier

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Lever l'exclusion d'un dossier

Retire le marqueur « jamais public ici ». Ne rend rien public : cela rend seulement le dossier à nouveau éligible à une propagation, qui reste un geste distinct.

Idempotent.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
folder_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant du dossier

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Lire l'état d'accès public d'un document

Rend l'état complet du document : publique ou non, quelle racine l'explique, s'il est exclu et par quoi.

Le champ reason porte le diagnostic quand le document n'est pas public. stale y est le cas le plus instructif : le document a été estampillé un jour, mais sa racine a été dépubliée ou lui-même déplacé — la concession est périmée, sans qu'aucune écriture n'ait été nécessaire.

subtree est toujours null : un document n'a pas de sous-arbre.

Exige le droit d'écriture sur le document (cf. l'endpoint dossier).

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
file_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed887

Identifiant du document

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Exclure un document de l'accès public

Pose le marqueur « jamais public ici » sur le document et coupe l'accès immédiatement : la concession qu'il portait est retirée.

C'est le SEUL moyen de retirer une ressource d'un sous-arbre public sans dépublier la racine entière.

Le marqueur survit aux repropagations et voyage avec le document : déplacé dans un autre sous-arbre public, il reste exclu — un marqueur de confidentialité qui s'évaporerait au déplacement serait le pire des deux mondes.

Idempotent : 200 si l'exclusion existait déjà, 201 sinon.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
file_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed887

Identifiant du document

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Lever l'exclusion d'un document

Retire le marqueur « jamais public ici ». Ne rend rien public : le document redevient seulement éligible à une propagation, qu'il faut déclencher explicitement sur la racine (POST …/public_access/propagate).

Idempotent.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
file_id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed887

Identifiant du document

Responses

Response samples

Content type
application/json
{
  • "resource": {
    },
  • "public": true,
  • "reason": "not_stamped",
  • "published_root": true,
  • "root": {
    },
  • "excluded": false,
  • "excluded_by": {
    },
  • "granted_count": 42,
  • "subtree": {
    }
}

Mass Communications

Mass communication campaigns

Lister les communications de masse

Récupère la liste des communications de masse de l'utilisateur.

Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
q[name_cont]
string

Filtrer par nom (contient)

q[status_eq]
string
Enum: "draft" "sending" "sent" "failed"

Filtrer par statut

Responses

Response samples

Content type
application/json
{
  • "mass_communications": [
    ]
}

Créer une communication de masse

Crée une nouvelle communication de masse avec ses destinataires et pièces jointes.

Modes de création:

  • Brouillon (par défaut): La communication est créée mais pas envoyée
  • Envoi immédiat (send=true): La communication est créée et envoyée immédiatement

Destinataires: Les destinataires peuvent être fournis de deux façons:

  • Directement dans le JSON avec email, prénom, nom
  • Via un fichier CSV/Excel uploadé dans le champ file

Variables de template: Le corps du message supporte les variables Liquid:

  • {{ recipient.first_name }} - Prénom du destinataire
  • {{ recipient.last_name }} - Nom du destinataire
  • {{ recipient.email }} - Email du destinataire
  • {{ recipient.custom_attributes.xxx }} - Attributs personnalisés
Authorizations:
OAuth2PasswordOAuth2AuthCode
Request Body schema:
required
required
object
required
Array of objects non-empty

Liste des destinataires

Array of objects

Pièces jointes

send
boolean
Default: false

Envoyer immédiatement après création

Responses

Request samples

Content type
{
  • "mass_communication": {
    },
  • "recipients": [
    ],
  • "send": false
}

Response samples

Content type
application/json
{
  • "mass_communication": {
    },
  • "recipients": [
    ],
  • "attachments": [ ],
  • "skipped_recipients": [ ],
  • "sending": false,
  • "enqueued_count": 0
}

Récupérer une communication de masse

Récupère les détails d'une communication de masse avec ses destinataires et pièces jointes.

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "mass_communication": {
    },
  • "recipients": [
    ],
  • "attachments": [
    ]
}