> ## Documentation Index > Fetch the complete documentation index at: https://developers.marko.fr/llms.txt > Use this file to discover all available pages before exploring further. # Lancer un workflow maintenant > Déclenche une exécution manuelle d'un workflow personnalisé. **Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation). **Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency). [Workflows et extraction IA](/workflows-guide). ## OpenAPI ````yaml /openapi.json post /workflows/workflow-definitions/{definition_id}/run openapi: 3.1.0 info: title: MARKO External Partner API version: v1 description: >- Stable external API contract for the live environment. Authentication flow for partner integrations: 1. Generate an API key from the MARKO entity admin API section. 2. Keep the raw API secret server-side and use it only to sign `POST /v1/auth/token`. 3. Build the canonical message `MARKO-EXTERNAL-API-TOKEN-V1\n{key_id}\n{timestamp}\n{nonce}`. 4. Sign that message with HMAC-SHA256 and send the hex signature with `key_id`, `timestamp` and `nonce`. 5. Use the returned short-lived bearer on business endpoints as `Authorization: Bearer `. The raw API secret must never be sent on business endpoints. This public contract intentionally excludes beta endpoints. Référence enrichie pour les développeurs et les assistants IA. Exemples synthétiques; les champs sont extraits des modèles et sérialiseurs de la version indiquée dans x-documentation-provenance. servers: - url: https://partner-api.marko.fr/v1 security: - BearerAuth: [] tags: - name: auth x-group: Authentification - name: entity x-group: Entité - name: portfolio x-group: Portefeuille - name: deals x-group: Deals - name: fonds x-group: Fonds - name: spvs x-group: SPV - name: operations x-group: Opérations - name: taxonomies x-group: Taxonomies - name: import-jobs x-group: Imports par lot - name: comments x-group: Commentaires - name: documents x-group: Documents - name: users x-group: Utilisateurs - name: settings x-group: Paramètres - name: rcci x-group: Conformité RCCI - name: field-definitions x-group: Champs métier - name: search x-group: Recherche - name: operateurs x-group: Opérateurs - name: alerts x-group: Alertes - name: notifications x-group: Notifications - name: calendar x-group: Calendrier - name: enrichment x-group: Enrichissement SIREN - name: reports x-group: Exports - name: reporting x-group: Templates de reporting - name: workflows x-group: Workflows et extraction IA - name: tasks x-group: Tâches externalDocs: description: Download the matching Postman collection. url: /v1/postman.json paths: /workflows/workflow-definitions/{definition_id}/run: post: tags: - workflows summary: Lancer un workflow maintenant description: >- Déclenche une exécution manuelle d'un workflow personnalisé. **Scope requis :** `workflows:write`. [Scopes et délégation](/scopes-and-delegation). **Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency). [Workflows et extraction IA](/workflows-guide). operationId: workflows_run parameters: - in: path name: definition_id required: true schema: type: string title: Definition Id example: custom-workflow-1 description: >- Paramètre definition_id pour cette route; type, format et contraintes ci-dessous. - in: header name: X-Request-ID required: false description: >- Partner-generated correlation identifier echoed in logs and error payloads. schema: type: string example: marko-workflows-run - in: header name: Idempotency-Key required: true description: >- Required for every write, including environments where replay deduplication is disabled. Reuse the same value when retrying the same logical write and use a new value for a different write. schema: type: string maxLength: 255 pattern: ^[!-~]+$ responses: '202': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkflowRunAccepted' example: workflow: id: custom-workflow-1 name: Exemple MARKO description: example type: example schedule: example enabled: false custom: false editable: false deletable: false toggleable: false source: example scope: example impact: example job_types: [] preset_key: null status: instruction schedule_kind: null schedule_config: {} config: {} last_run_at: null next_run_at: null last_error: null run: id: 11111111-1111-4111-8111-111111111111 workflow_id: example workflow_name: null workflow_source: custom job_type: null preset_key: null status: queued entity_type: null entity_id: null retry_count: 0 error_message: null result: {} created_at: null started_at: null completed_at: null trigger_mode: example headers: Idempotency-Key: schema: type: string description: Clé d'idempotence utilisée pour l'action. X-Marko-Idempotency-Key-Source: schema: type: string enum: - client - server description: Origine de la clé utilisée. X-Marko-Idempotency-TTL-Seconds: schema: type: integer description: Durée de rétention annoncée pour cette action, en secondes. '400': description: Invalid Idempotency-Key header content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Bad Request status: 400 detail: >- Idempotency-Key must contain at most 255 visible ASCII characters without spaces. request_id: req_example_partner_call '401': description: Authentication required content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Unauthorized status: 401 detail: A valid bearer token is required. request_id: req_example_partner_call '403': description: Scope, route or IP restriction content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Forbidden status: 403 detail: The API key does not allow this operation. request_id: req_example_partner_call '404': description: >- Not Found — refus déclaré dans le handler ou un helper de cette route. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '409': description: Idempotency or write target conflict content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Conflict status: 409 detail: >- The idempotency key payload, external reference, target, or source conflicts with an existing write. request_id: req_example_partner_call '422': description: Validation failed content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Unprocessable Content status: 422 detail: The request payload or parameters are invalid. request_id: req_example_partner_call '428': description: Required Idempotency-Key header is missing content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Precondition Required status: 428 detail: The Idempotency-Key header is required. request_id: req_example_partner_call '429': description: Rate limit or progressive ban headers: Retry-After: description: Cooldown in seconds before retrying the request. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Too Many Requests status: 429 detail: The request rate limit was exceeded. request_id: req_example_partner_call '500': description: Unexpected server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: about:blank title: Internal Server Error status: 500 detail: An unexpected server error occurred. request_id: req_example_partner_call deprecated: false security: - BearerAuth: [] components: schemas: WorkflowRunAccepted: type: object properties: workflow: $ref: '#/components/schemas/WorkflowDefinition' description: Workflow associé à l'exécution acceptée. run: $ref: '#/components/schemas/WorkflowRun' description: Exécution créée ou retrouvée pour ce workflow. required: - workflow - run ProblemDetails: type: object required: - title - status - detail properties: type: type: string default: about:blank description: >- URI identifiant le type de problème; about:blank lorsque seul le statut HTTP le caractérise. title: type: string description: Titre affiché pour l'événement ou le problème. status: type: integer description: Statut HTTP de la réponse d'erreur. detail: type: string description: Informations détaillées sur le problème ou le dossier. request_id: type: string description: Identifiant de corrélation pour le diagnostic de la requête. scope: type: string description: Scope concerné par le refus d'accès, lorsqu'il est renseigné. route_id: type: string description: Identifiant de la route concernée par le problème. reason_code: type: string description: >- Code structuré du motif de refus; préférable au texte du message pour le diagnostic. WorkflowDefinition: type: object properties: id: type: string description: Clé du workflow, pas nécessairement un UUID. name: type: string description: >- Nom de la ressource. Les recherches exactes et partielles sont décrites au niveau de la route. description: type: string description: Description libre de la ressource. type: type: string description: Famille de traitement de cette définition de workflow. schedule: type: string description: Planification actuelle du workflow. enabled: type: boolean description: Indique si cette définition est activée. custom: type: boolean description: Indique si le workflow est une définition personnalisée. editable: type: boolean description: Indique si cette définition de workflow peut être modifiée. deletable: type: boolean description: Indique si cette définition de workflow peut être supprimée. toggleable: type: boolean description: >- Indique si cette définition de workflow peut être activée ou désactivée. source: type: string description: >- Origine de cette définition de workflow; distingue les workflows système des workflows personnalisés. scope: type: string description: >- Périmètre métier couvert par le workflow; distinct des scopes d'autorisation de la clé API. impact: type: string description: Indication de l'effet métier attendu du preset. job_types: type: array items: type: string description: Types de traitements associés à cette définition de workflow. preset_key: anyOf: - type: string - type: 'null' description: >- Clé du preset de workflow; utiliser une valeur du catalogue de presets. status: type: string description: >- État de la définition de workflow: draft, active, inactive ou error. Distinct du résultat d'une exécution. schedule_kind: anyOf: - type: string - type: 'null' description: 'Mode de planification: utiliser une valeur du catalogue de presets.' schedule_config: type: object additionalProperties: true description: Objet JSON métier; les clés dépendent de la source ou du preset. config: type: object additionalProperties: true description: Objet JSON métier; les clés dépendent de la source ou du preset. last_run_at: anyOf: - type: string format: date-time - type: 'null' description: Date de la dernière exécution du workflow. next_run_at: anyOf: - type: string format: date-time - type: 'null' description: Date de la prochaine exécution planifiée, si elle existe. last_error: anyOf: - type: string - type: 'null' description: Dernière erreur enregistrée pour cette définition de workflow. required: - id - name - description - type - schedule - enabled - custom - editable - deletable - toggleable - source - scope - impact - job_types - preset_key - status - schedule_kind - schedule_config - config - last_run_at - next_run_at - last_error WorkflowRun: type: object properties: id: type: string format: uuid description: Identifiant MARKO de la ressource. workflow_id: type: string description: >- Clé du workflow; certaines routes utilisent une chaîne, d'autres un UUID. Respectez le type de cette route. workflow_name: anyOf: - type: string - type: 'null' description: Nom du workflow à l'origine de l'exécution. workflow_source: type: string const: custom description: Origine du workflow à l'origine de l'exécution. job_type: anyOf: - type: string - type: 'null' description: Type de traitement exécuté par le job. preset_key: anyOf: - type: string - type: 'null' description: >- Clé du preset de workflow; utiliser une valeur du catalogue de presets. status: type: string description: >- État de cette exécution de workflow; consulter error_message en cas d'échec et les dates de début et de fin. entity_type: anyOf: - type: string - type: 'null' description: Type de ressource auquel se rapporte la vue ou le traitement. entity_id: anyOf: - type: string format: uuid - type: 'null' description: >- Identifiant de la ressource ciblée par le job, dont le type est donné par entity_type; ce n'est pas nécessairement l'entité administrative. retry_count: type: integer description: Nombre de reprises enregistrées pour ce traitement. error_message: anyOf: - type: string - type: 'null' description: Détail de l'échec, lorsqu'il est disponible. result: type: object additionalProperties: true description: Objet JSON métier; les clés dépendent de la source ou du preset. created_at: anyOf: - type: string format: date-time - type: 'null' description: Date de création au format ISO 8601. started_at: anyOf: - type: string format: date-time - type: 'null' description: Date de début du traitement. completed_at: anyOf: - type: string format: date-time - type: 'null' description: Date de fin, lorsqu'une exécution ou un traitement est terminé. trigger_mode: type: string description: Mode qui a déclenché cette exécution. required: - id - workflow_id - workflow_name - workflow_source - job_type - preset_key - status - entity_type - entity_id - retry_count - error_message - result - created_at - started_at - completed_at - trigger_mode securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: MARKO short-lived bearer description: >- Use the `access_token` returned by `POST /v1/auth/token`. Do not send the raw API secret on business endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.