Templates

Templates define the structure of a checklist — sections, steps, types, conditions, and execution settings. Create templates via the API or use the visual editor at my.rundun.app.

Template bodies follow the TDL (Template Definition Language) schema. Read the TDL reference for the full field-by-field spec.

POST /v1/templates

Create a new template in your organization. The request body is a TDL object.

curl -X POST https://api.rundun.app/v1/templates \
  -H "Authorization: Bearer rdk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "STR turnover check",
    "description": "Cleaning and preparation checklist for short-term rental turnover",
    "tags": ["STR", "cleaning"],
    "settings": {
      "allow_skip": false,
      "signature_on_complete": false,
      "est_minutes": 15
    },
    "sections": [
      {
        "id": "g-kit1",
        "title": "Kitchen",
        "steps": [
          {
            "id": "s-kc01",
            "type": "boolean",
            "label": "Dishes washed and put away?",
            "required": true,
            "photo": false,
            "geo": false,
            "config": { "true_label": "Yes", "false_label": "No" }
          },
          {
            "id": "s-kp01",
            "type": "photo",
            "label": "Photo of clean kitchen",
            "required": true,
            "config": { "min": 1, "max": 3 }
          }
        ]
      },
      {
        "id": "g-bed1",
        "title": "Bedroom",
        "steps": [
          {
            "id": "s-bl01",
            "type": "boolean",
            "label": "Fresh linen on all beds?",
            "required": true,
            "photo": { "min": 0, "max": 2 },
            "geo": false,
            "config": { "true_label": "Yes", "false_label": "No" }
          }
        ]
      }
    ],
    "execution": {
      "scope": "any",
      "identity_required": "none"
    }
  }'

Response

{
  "id": "t-550e8400-e29b-41d4-a716-446655440000",
  "v": 1,
  "name": "STR turnover check",
  "org_id": "org-550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-05-22T08:00:00Z",
  "sections": [ ... ]
}

The API assigns id, v, and org_id — do not include these in your request body.

GET /v1/templates

List all templates in your organization.

curl https://api.rundun.app/v1/templates \
  -H "Authorization: Bearer rdk_live_..."

Response

{
  "data": [
    {
      "id": "t-550e8400-e29b-41d4-a716-446655440000",
      "v": 3,
      "name": "STR turnover check",
      "description": "Cleaning and preparation checklist for short-term rental turnover",
      "tags": ["STR", "cleaning"],
      "created_at": "2026-05-22T08:00:00Z",
      "updated_at": "2026-05-22T09:00:00Z"
    }
  ],
  "pagination": { "total": 12, "page": 1, "per_page": 50, "next_page": null }
}

GET /v1/templates/:template_id

Retrieve the full TDL for a single template.

curl https://api.rundun.app/v1/templates/t-550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer rdk_live_..."

Returns the complete TDL object including all sections, steps, and execution settings.

PATCH /v1/templates/:template_id

Update a template. Send a partial TDL object — only the fields you include are updated. The version counter v is incremented automatically.

Important: Updating a template does not affect runs already dispatched. Each run holds a verbatim snapshot of the template at the time of dispatch.

curl -X PATCH https://api.rundun.app/v1/templates/t-550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer rdk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "STR turnover check v2", "settings": { "est_minutes": 20 } }'

DELETE /v1/templates/:template_id

Delete a template. This does not affect existing runs — their snapshots are preserved.

curl -X DELETE https://api.rundun.app/v1/templates/t-550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer rdk_live_..."

Returns 204 No Content on success.

POST /v1/templates/generate

Generate a template from a natural language prompt using AI (our AI model). The response is a complete, valid TDL object ready to be saved or modified.

curl -X POST https://api.rundun.app/v1/templates/generate \
  -H "Authorization: Bearer rdk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Vehicle pre-rental inspection checklist for a car rental company. Include exterior condition, interior cleanliness, fuel level, odometer, and customer signature." }'

Response

The response is a full TDL object that you can review and then save with POST /v1/templates:

{
  "name": "Vehicle pre-rental inspection",
  "description": "Pre-rental condition check before handing keys to customer",
  "tags": ["vehicle", "rental", "inspection"],
  "settings": {
    "allow_skip": false,
    "signature_on_complete": true,
    "est_minutes": 5
  },
  "sections": [
    {
      "id": "g-ext1",
      "title": "Exterior",
      "steps": [
        {
          "id": "s-od01",
          "type": "number",
          "label": "Odometer reading",
          "hint": null,
          "required": true,
          "photo": false,
          "geo": false,
          "config": { "unit": "km", "min": 0, "decimal": 0 }
        },
        {
          "id": "s-fu01",
          "type": "choice",
          "label": "Fuel level",
          "required": true,
          "photo": false,
          "geo": false,
          "config": {
            "options": [
              { "id": "o-fu1", "label": "Full" },
              { "id": "o-fu2", "label": "3/4" },
              { "id": "o-fu3", "label": "1/2" },
              { "id": "o-fu4", "label": "1/4" }
            ]
          }
        },
        {
          "id": "s-dm01",
          "type": "boolean",
          "label": "Any pre-existing damage?",
          "required": true,
          "photo": false,
          "geo": false,
          "config": { "true_label": "Yes", "false_label": "No" }
        },
        {
          "id": "s-dm02",
          "type": "text",
          "label": "Describe the damage",
          "required": true,
          "photo": { "min": 1, "max": 6 },
          "geo": false,
          "condition": { "when": { "step": "s-dm01", "op": "eq", "value": true } },
          "config": { "multiline": true, "placeholder": "Location and description" }
        }
      ]
    },
    {
      "id": "g-int1",
      "title": "Interior",
      "steps": [
        {
          "id": "s-cl01",
          "type": "rating",
          "label": "Interior cleanliness",
          "required": true,
          "photo": { "min": 0, "max": 3 },
          "geo": false,
          "config": { "min": 1, "max": 5, "low_label": "Very dirty", "high_label": "Spotless" }
        }
      ]
    }
  ],
  "execution": {
    "scope": "any",
    "identity_required": "none"
  }
}

The generated template does not include an id — save it with POST /v1/templates to persist it. You can modify the JSON before saving.