Aller au contenu
TellMeHow Documentation
fr

Documentation de l’API

Livrable

Livrable : 20 opérations de l’API, avec leurs paramètres, leur corps, leurs réponses et un exemple curl.

POST /engagements/{engagement}/deliverable/comments/{comment}/close

Écriture deliverables.comments.close

Paramètres

engagement chemin
Identifiant (ULID).
comment chemin
Identifiant (ULID).

Réponses

  • 201 Créé (200 ou 202 pour une action ou un traitement asynchrone).
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X POST "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/comments/{comment}/close" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/deliverable/comments/{comment}/reply

Écriture deliverables.comments.reply

Paramètres

engagement chemin
Identifiant (ULID).
comment chemin
Identifiant (ULID).

Corps application/json

  • body string requis

    longueur : au plus 5000

Réponses

  • 201 Créé (200 ou 202 pour une action ou un traitement asynchrone).
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X POST "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/comments/{comment}/reply" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"body":"…"}'

GET /engagements/{engagement}/deliverable/documents

Lecture deliverables.documents.index

Paramètres

engagement chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/documents" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/deliverable/documents/generate-all

Écriture deliverables.documents.generate-all

Paramètres

engagement chemin
Identifiant (ULID).

Corps application/json

  • ai boolean

Réponses

  • 201 Créé (200 ou 202 pour une action ou un traitement asynchrone).
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X POST "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/documents/generate-all" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"ai":true}'

GET /engagements/{engagement}/deliverable/documents/{kind}

Lecture deliverables.documents.show

Paramètres

engagement chemin
Identifiant (ULID).
kind chemin
Valeur d’une liste fixe (type, langue, niveau…).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/documents/{kind}" \
  -H "Authorization: Bearer pat_…"

PATCH /engagements/{engagement}/deliverable/documents/{kind}

Écriture deliverables.documents.update

Paramètres

engagement chemin
Identifiant (ULID).
kind chemin
Valeur d’une liste fixe (type, langue, niveau…).

Corps application/json

  • updated_at string requis

    longueur : au plus 64

  • included boolean
  • parameters array<object>
  • blocks array<array<object>>

    éléments : au plus 200

  • blocks[].id string | null

    longueur : au plus 64

  • blocks[].type object requis

    une valeur parmi heading paragraph message key_figures item_list table chart process quote callout

  • blocks[].level integer | null
  • blocks[].text string | null

    longueur : au plus 5000

  • blocks[].title string | null

    longueur : au plus 200

  • blocks[].refs array<object>

    éléments : au plus 50

  • blocks[].refs[].type object requis

    une valeur parmi finding opportunity process process_step contradiction evidence tool topic follow_up

  • blocks[].refs[].id string requis

    longueur : au plus 64

  • blocks[].data_ref string | null

    longueur : au plus 64

  • blocks[].items array<string>

    éléments : au plus 50

  • blocks[].item_type object

    une valeur parmi finding opportunity process process_step contradiction evidence tool topic follow_up

  • blocks[].ids array<string>

    éléments : au plus 50

  • blocks[].display object

    une valeur parmi compact full

  • blocks[].options array<object> | null
  • blocks[].chart object

    une valeur parmi gain_effort_matrix pain_heatmap coverage_bars topic_coverage roadmap_lanes

  • blocks[].process_id string | null

    longueur : au plus 64

  • blocks[].show_map boolean
  • blocks[].evidence_id string | null

    longueur : au plus 64

  • blocks[].theme string | null

    longueur : au plus 64

  • blocks[].tone object

    une valeur parmi info caution

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X PATCH "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/documents/{kind}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"updated_at":"…"}'

POST /engagements/{engagement}/deliverable/documents/{kind}/generate

Écriture deliverables.documents.generate

Paramètres

engagement chemin
Identifiant (ULID).
kind chemin
Valeur d’une liste fixe (type, langue, niveau…).

Corps application/json

  • mode object

    une valeur parmi keep_edits replace_all

  • process_id string | null
  • ai boolean

Réponses

  • 201 Créé (200 ou 202 pour une action ou un traitement asynchrone).
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X POST "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/documents/{kind}/generate" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"mode":"keep_edits","process_id":"01JABCDEFGHJKMNPQRSTVWXYZ0","ai":true}'

GET /engagements/{engagement}/deliverable/draft

Lecture deliverables.draft.show

Paramètres

engagement chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/draft" \
  -H "Authorization: Bearer pat_…"

PATCH /engagements/{engagement}/deliverable/draft

Écriture deliverables.draft.update

Paramètres

engagement chemin
Identifiant (ULID).

Corps application/json

  • introduction string | null

    longueur : au plus 20000

  • recommendations string | null

    longueur : au plus 20000

  • attribution object

    une valeur parmi by_role named

  • named_interview_ids array<string>
  • include_proposed boolean
  • dismiss_suggestion boolean
  • stage object

    une valeur parmi interim final

  • auto_refresh_interim boolean

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X PATCH "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/draft" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"introduction":"…","recommendations":"…","attribution":"by_role"}'

GET /engagements/{engagement}/deliverable/draft/evidences/{evidence}/preview

Lecture deliverables.draft.evidences.preview

Paramètres

engagement chemin
Identifiant (ULID).
evidence chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/draft/evidences/{evidence}/preview" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/deliverable/draft/preview

Lecture deliverables.draft.preview

Paramètres

engagement chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/draft/preview" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/deliverable/draft/suggest-recommendations

Écriture deliverables.draft.suggest

Paramètres

engagement chemin
Identifiant (ULID).

Réponses

  • 201 Créé (200 ou 202 pour une action ou un traitement asynchrone).
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X POST "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/draft/suggest-recommendations" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/deliverable/publish

Écriture deliverables.publish

Paramètres

engagement chemin
Identifiant (ULID).

Corps application/json

  • changelog string | null

    longueur : au plus 5000

  • stage object

    une valeur parmi interim final

Réponses

  • 201 Créé (200 ou 202 pour une action ou un traitement asynchrone).
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X POST "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/publish" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"changelog":"…","stage":"interim"}'

GET /engagements/{engagement}/deliverable/versions

Lecture deliverables.versions.index

Paramètres

engagement chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/versions" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/deliverable/versions/{version}

Lecture deliverables.versions.show

Paramètres

engagement chemin
Identifiant (ULID).
version chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/versions/{version}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/deliverable/versions/{version}/comments

Lecture deliverables.versions.comments.index

Paramètres

engagement chemin
Identifiant (ULID).
version chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/versions/{version}/comments" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/deliverable/versions/{version}/snapshot

Lecture deliverables.versions.snapshot

Paramètres

engagement chemin
Identifiant (ULID).
version chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/deliverable/versions/{version}/snapshot" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/exports

Lecture deliverables.exports.index

Paramètres

engagement chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/exports" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/exports

Écriture deliverables.exports.store

Paramètres

engagement chemin
Identifiant (ULID).

Corps application/json

  • kind object requis

    une valeur parmi bpmn findings_csv opportunities_csv json_bundle printable document_pdf document_pptx document_docx document_csv deliverable_pdf

  • deliverable_version_id string | null
  • process_id string | null
  • document_kind object

    une valeur parmi coverage interim_insights methodology executive_summary roadmap process_sheets tool_landscape role_activity pain_map uncertainties verbatims

Réponses

  • 201 Créé (200 ou 202 pour une action ou un traitement asynchrone).
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl -X POST "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/exports" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"bpmn"}'

GET /engagements/{engagement}/exports/{export}/download

Lecture deliverables.exports.download

Paramètres

engagement chemin
Identifiant (ULID).
export chemin
Identifiant (ULID).
cursor limit requête
Pagination par curseur, pour les opérations qui rendent une liste paginée.

Réponses

  • 200 Succès : la ressource dans data.
  • 401 Jeton absent, invalide, révoqué ou expiré.
  • 403 Non autorisé par le rôle, une règle ou la portée.
  • 404 Ressource inconnue ou hors de l’espace.
  • 422 Données invalides (validation.failed).
  • 429 Limite de débit atteinte.
Exemple 
curl "https://{votre-espace}.tellmehow.io/api/v1/engagements/{engagement}/exports/{export}/download" \
  -H "Authorization: Bearer pat_…"