Mankomail

Templates ​

Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.

GET /api/v1/templates ​

List the templates of the instance

What the member can install. An administrator receives the same shape, disabled templates included.

Access — Member session or API key with scope templates:read.

Responses

200 — The templates.

FieldTypeRequired
templatesobject[]yes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "templates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "enabled": { "type": "boolean" },
          "nodeTypes": { "type": "array", "items": { "type": "string" } },
          "requiresProviders": { "type": "array", "items": { "type": "string" } },
          "createdBy": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              { "type": "null" }
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
          },
          "installCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
        },
        "required": [
          "id",
          "name",
          "description",
          "category",
          "enabled",
          "nodeTypes",
          "requiresProviders",
          "createdBy",
          "createdAt",
          "updatedAt",
          "installCount"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "templates" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

GET /api/v1/templates/{id} ​

Read a template and its graph

The graph travels so the installation can be a considered choice. For a member, a disabled template is the same 404 as an unknown id.

Access — Member session or API key with scope templates:read.

Parameters

NameInTypeRequired
idpathstringyes

Responses

200 — The template.

FieldTypeRequired
templateobjectyes
graphobjectyes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "name": { "type": "string" },
        "description": { "type": "string" },
        "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
        "enabled": { "type": "boolean" },
        "nodeTypes": { "type": "array", "items": { "type": "string" } },
        "requiresProviders": { "type": "array", "items": { "type": "string" } },
        "createdBy": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            { "type": "null" }
          ]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        "installCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
      },
      "required": [
        "id",
        "name",
        "description",
        "category",
        "enabled",
        "nodeTypes",
        "requiresProviders",
        "createdBy",
        "createdAt",
        "updatedAt",
        "installCount"
      ],
      "additionalProperties": false
    },
    "graph": {
      "type": "object",
      "properties": {
        "id": {},
        "workflowId": {},
        "nodes": {
          "readOnly": true,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {},
              "type": { "type": "string", "minLength": 1, "maxLength": 128 },
              "version": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "name": { "type": "string", "minLength": 1, "maxLength": 200 },
              "params": {
                "default": {},
                "type": "object",
                "propertyNames": { "type": "string" },
                "additionalProperties": {}
              },
              "onError": {
                "default": "fail",
                "type": "string",
                "enum": [ "fail", "continue", "errorPort" ]
              },
              "retry": {
                "type": "object",
                "properties": {
                  "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
                  "delayMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
                },
                "required": [ "maxAttempts" ],
                "additionalProperties": false
              },
              "timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
              "position": {
                "type": "object",
                "properties": { "x": { "type": "number" }, "y": { "type": "number" } },
                "required": [ "x", "y" ],
                "additionalProperties": false
              },
              "disabled": { "type": "boolean" },
              "notes": { "type": "string", "maxLength": 2000 }
            },
            "required": [ "id", "type", "version", "name", "params", "onError" ],
            "additionalProperties": false
          }
        },
        "connections": {
          "readOnly": true,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "from": {},
              "output": { "type": "string" },
              "to": {},
              "input": { "type": "string" },
              "kind": { "type": "string", "enum": [ "data", "service" ] }
            },
            "required": [ "from", "output", "to" ],
            "additionalProperties": false
          }
        },
        "notes": {
          "readOnly": true,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "string", "minLength": 1, "maxLength": 64 },
              "text": { "default": "", "type": "string", "maxLength": 4000 },
              "position": {
                "type": "object",
                "properties": { "x": { "type": "number" }, "y": { "type": "number" } },
                "required": [ "x", "y" ],
                "additionalProperties": false
              },
              "size": {
                "default": { "width": 240, "height": 160 },
                "type": "object",
                "properties": {
                  "width": { "type": "number", "minimum": 120, "maximum": 2000 },
                  "height": { "type": "number", "minimum": 80, "maximum": 2000 }
                },
                "required": [ "width", "height" ],
                "additionalProperties": false
              },
              "color": {
                "default": "jaune",
                "type": "string",
                "enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
              }
            },
            "required": [ "id", "text", "position", "size", "color" ],
            "additionalProperties": false
          }
        },
        "pins": {
          "type": "object",
          "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
          "additionalProperties": {
            "type": "object",
            "properties": {
              "output": {},
              "port": { "type": "string" },
              "pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
            },
            "required": [ "output", "pinnedAt" ],
            "additionalProperties": false
          }
        }
      },
      "required": [ "id", "workflowId", "nodes", "connections" ],
      "additionalProperties": false
    }
  },
  "required": [ "template", "graph" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — templates.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

POST /api/v1/templates/{id}/install ​

Install a template as a new draft

Creates a draft workflow owned by the member from a copy of the template graph; publishing stays an explicit step. A template using a node type the organisation forbids to this member is refused (409 templates.forbidden_node, the types in details.nodeTypes).

Access — Member session or API key with scope workflows:write.

Parameters

NameInTypeRequired
idpathstringyes

Request body (application/json)

FieldTypeRequired
namestringno
JSON Schema
json
{
  "type": "object",
  "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }
}

Responses

201 — The id of the new workflow.

FieldTypeRequired
workflowIdstring (uuid)yes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "workflowId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [ "workflowId" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.

Error codes — request.bad_request, templates.not_found, templates.forbidden_node. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

Example request

json
{}

Example response (201)

json
{ "workflowId": "0192f1c2-dddd-7000-8000-000000000011" }

POST /api/v1/admin/templates/promote ​

Promote a workflow to a template

Freezes the graph of any member’s workflow (its published version, or its draft) as a template of the instance. A graph that fails validation is refused with 422 templates.invalid_graph and the diagnostic in details.validation.

Access — Member session or API key with scope admin:write (administrator role required).

Request body (application/json)

FieldTypeRequired
workflowIdstring (uuid)yes
namestringyes
descriptionstringyes
categorystring | nullno
JSON Schema
json
{
  "type": "object",
  "properties": {
    "workflowId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
    "description": { "type": "string", "maxLength": 2000 },
    "category": {
      "anyOf": [
        { "type": "string", "minLength": 1, "maxLength": 60 },
        { "type": "null" }
      ]
    }
  },
  "required": [ "workflowId", "name", "description" ]
}

Responses

201 — The template.

FieldTypeRequired
templateobjectyes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "name": { "type": "string" },
        "description": { "type": "string" },
        "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
        "enabled": { "type": "boolean" },
        "nodeTypes": { "type": "array", "items": { "type": "string" } },
        "requiresProviders": { "type": "array", "items": { "type": "string" } },
        "createdBy": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            { "type": "null" }
          ]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        "installCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
      },
      "required": [
        "id",
        "name",
        "description",
        "category",
        "enabled",
        "nodeTypes",
        "requiresProviders",
        "createdBy",
        "createdAt",
        "updatedAt",
        "installCount"
      ],
      "additionalProperties": false
    }
  },
  "required": [ "template" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.

Error codes — request.bad_request, templates.workflow_not_found, templates.invalid_graph. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

PUT /api/v1/admin/templates/{id} ​

Update the metadata of a template

Partial, and metadata only (name, description, category, enabled). category: null clears it, an absent key leaves it. The graph never changes: promote again for a new one.

Access — Member session or API key with scope admin:write (administrator role required).

Parameters

NameInTypeRequired
idpathstringyes

Request body (application/json)

FieldTypeRequired
namestringno
descriptionstringno
categorystring | nullno
enabledbooleanno
JSON Schema
json
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
    "description": { "type": "string", "maxLength": 2000 },
    "category": {
      "anyOf": [
        { "type": "string", "minLength": 1, "maxLength": 60 },
        { "type": "null" }
      ]
    },
    "enabled": { "type": "boolean" }
  }
}

Responses

200 — The template, updated.

FieldTypeRequired
templateobjectyes

Same schema as POST /api/v1/admin/templates/promote.

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request, templates.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

DELETE /api/v1/admin/templates/{id} ​

Delete a template

The workflows already installed from it are untouched: each received its own copy of the graph.

Access — Member session or API key with scope admin:write (administrator role required).

Parameters

NameInTypeRequired
idpathstringyes

Responses

204 — Deleted.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — templates.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.