checklist

Create a reusable checklist and return its CL-NNNN id: a name, a category and an optional description. Add the steps with checklist_item_add. Free tier: 3 checklists, and unlimited runs of them.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "description": "What the checklist is, e.g. Pre-delivery vehicle check or Site handover"
    },
    "category": {
      "type": "string",
      "maxLength": 60,
      "description": "A grouping key, lower-cased and hyphenated, e.g. handover or safety. Default general"
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "What this checklist is for and when to run it, printed at the top of a blank copy"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add one step to a checklist and return its I01-style id: the text, an optional section heading, and whether it is required. A required step that is unanswered or failed blocks sign-off; an optional one does not.

{
  "type": "object",
  "properties": {
    "checklist": {
      "type": "string",
      "maxLength": 200,
      "description": "The checklist id, e.g. CL-0001, or its name when only one carries it"
    },
    "text": {
      "type": "string",
      "maxLength": 2000,
      "description": "The step, as the person doing it will read it, e.g. Tyre pressures checked and recorded"
    },
    "section": {
      "type": "string",
      "maxLength": 60,
      "description": "A heading to group this step under, e.g. Exterior. Steps keep the order they were added within a section"
    },
    "required": {
      "type": "boolean",
      "description": "Whether sign-off is blocked while this step is unanswered or failed. Default true"
    },
    "note": {
      "type": "string",
      "maxLength": 2000,
      "description": "Guidance printed under the step, e.g. the tolerance or the standard it is checked against"
    },
    "position": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Insert at this 1-based position instead of at the end. Existing steps keep their ids"
    }
  },
  "required": [
    "checklist",
    "text"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Remove one step from a checklist by its I01-style id and bump the checklist version. Runs already under way keep the step they started with, so nothing anybody already ticked is rewritten.

{
  "type": "object",
  "properties": {
    "checklist": {
      "type": "string",
      "maxLength": 200,
      "description": "The checklist id, e.g. CL-0001, or its name when only one carries it"
    },
    "item": {
      "type": "string",
      "maxLength": 16,
      "description": "The step id, e.g. I03, as shown by checklist_show"
    }
  },
  "required": [
    "checklist",
    "item"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One checklist with its steps in order, grouped by section, plus how many are required and how many runs have been started from it. Pass as_text for a blank printable copy with a box against each step.

{
  "type": "object",
  "properties": {
    "checklist": {
      "type": "string",
      "maxLength": 200,
      "description": "The checklist id, e.g. CL-0001, or its name when only one carries it"
    },
    "as_text": {
      "type": "boolean",
      "description": "Return a blank printable copy as plain text as well as the structured view. Default false"
    }
  },
  "required": [
    "checklist"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Every checklist with its category, version, step count and how many runs came from it. Filter by category or by a word in the name. Returns at most 500 rows, newest change first.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "maxLength": 60,
      "description": "Only checklists in this category, matched after the same lower-case hyphenation applied on create"
    },
    "contains": {
      "type": "string",
      "maxLength": 200,
      "description": "Only checklists whose name contains this text, matched case-insensitively"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a checklist and its steps for good. Runs already started from it are untouched and stay readable: a run carries its own copy of the steps, so deleting the checklist does not erase what anybody signed.

{
  "type": "object",
  "properties": {
    "checklist": {
      "type": "string",
      "maxLength": 200,
      "description": "The checklist id, e.g. CL-0001, or its name when only one carries it"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true. There is no undo and nothing is copied anywhere first"
    }
  },
  "required": [
    "checklist",
    "confirm"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Start a dated run of a checklist and return its RUN-YYYY-NNNN id. The steps are COPIED into the run, so editing the checklist afterwards never changes a run already under way. Runs are free and never capped.

{
  "type": "object",
  "properties": {
    "checklist": {
      "type": "string",
      "maxLength": 200,
      "description": "The checklist id, e.g. CL-0001, or its name when only one carries it"
    },
    "title": {
      "type": "string",
      "maxLength": 200,
      "description": "What this run is against, e.g. Van BX21 KLM, February service"
    },
    "reference": {
      "type": "string",
      "maxLength": 64,
      "description": "The job, order or asset id this run belongs to, e.g. WO-2026-0044. Named only; no sibling store is opened"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the run happened, YYYY-MM-DD. Default today"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "checklist",
    "title"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Mark one step pass, fail or na, with who did it and when. na means the step did not apply; it counts as answered and never as passed. A step can be answered again while the run is open, and the last answer stands.

{
  "type": "object",
  "properties": {
    "run": {
      "type": "string",
      "maxLength": 200,
      "description": "The run id, e.g. RUN-2026-0001, or its title when only one carries it"
    },
    "item": {
      "type": "string",
      "maxLength": 16,
      "description": "The step id, e.g. I03, as shown by run_show"
    },
    "state": {
      "type": "string",
      "enum": [
        "pending",
        "pass",
        "fail",
        "na"
      ],
      "description": "pass, fail, na for did not apply, or pending to put the step back to unanswered"
    },
    "by": {
      "type": "string",
      "maxLength": 200,
      "description": "Who answered it. Printed against the step on the report"
    },
    "at": {
      "type": "string",
      "maxLength": 10,
      "description": "The day it was answered, YYYY-MM-DD. Default the run's own date"
    },
    "note": {
      "type": "string",
      "maxLength": 2000,
      "description": "What was found. Say why on a fail: the report prints this under the step"
    }
  },
  "required": [
    "run",
    "item",
    "state"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The whole run: every step with its answer, who answered it and when, grouped by section, plus the pass, fail and outstanding counts, the failures in full, and whether it can be signed off and why not.

{
  "type": "object",
  "properties": {
    "run": {
      "type": "string",
      "maxLength": 200,
      "description": "The run id, e.g. RUN-2026-0001, or its title when only one carries it"
    }
  },
  "required": [
    "run"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Runs newest first, with their checklist, progress and sign-off state. Filter by checklist, by status, by reference or to open runs only. Returns at most 500 rows.

{
  "type": "object",
  "properties": {
    "checklist": {
      "type": "string",
      "maxLength": 200,
      "description": "Only runs of this checklist, by id or name"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "complete",
        "signed_off",
        "abandoned"
      ],
      "description": "Only runs in this status"
    },
    "open_only": {
      "type": "boolean",
      "description": "Only open and complete runs, the ones still editable. Default false"
    },
    "reference": {
      "type": "string",
      "maxLength": 64,
      "description": "Only runs against this job, order or asset id, matched case-insensitively"
    },
    "with_failures": {
      "type": "boolean",
      "description": "Only runs that have at least one failed step. Default false"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Sign off a completed run with a name and a date, which freezes it. Refused while a required step is unanswered or failed, unless force is true, and either way the exceptions stay on the record and print on the report.

{
  "type": "object",
  "properties": {
    "run": {
      "type": "string",
      "maxLength": 200,
      "description": "The run id, e.g. RUN-2026-0001, or its title when only one carries it"
    },
    "by": {
      "type": "string",
      "maxLength": 200,
      "description": "Who is signing it off, as it should read on the document"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day it was signed, YYYY-MM-DD. Default today"
    },
    "note": {
      "type": "string",
      "maxLength": 2000,
      "description": "What the signature covers, or the exception being accepted"
    },
    "force": {
      "type": "boolean",
      "description": "Sign off even though required steps are unanswered or failed. Default false; the reasons come back either way"
    }
  },
  "required": [
    "run",
    "by"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Move a run back to open so a step can be answered again, or abandon it when the job did not happen. A signed-off run is refused: a signature is the point at which a run stops moving.

{
  "type": "object",
  "properties": {
    "run": {
      "type": "string",
      "maxLength": 200,
      "description": "The run id, e.g. RUN-2026-0001, or its title when only one carries it"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "abandoned"
      ],
      "description": "open puts a complete run back into edit; abandoned closes it without a signature"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the step happened, YYYY-MM-DD. Default today"
    },
    "note": {
      "type": "string",
      "maxLength": 2000,
      "description": "Why. Kept on the run's history and printed nowhere else"
    }
  },
  "required": [
    "run",
    "status"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The run as plain text on every tier: every step with its mark, who answered it, the notes, the counts and a signature block or the recorded signature. Pro also gets it back as a .txt download link valid for one hour, named by out_path.

{
  "type": "object",
  "properties": {
    "run": {
      "type": "string",
      "maxLength": 200,
      "description": "The run id, e.g. RUN-2026-0001, or its title when only one carries it"
    },
    "out_path": {
      "type": "string",
      "maxLength": 1000,
      "description": "Name for the downloaded .txt file, e.g. site-handover-run. Pro only. Omit to get the report back as text, which every tier can do; the file comes back as a download link valid for one hour"
    },
    "overwrite": {
      "type": "boolean",
      "description": "Replace out_path if a file is already there. Default false, and an existing file is refused with nothing written"
    }
  },
  "required": [
    "run"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a run for good, with every answer on it. A signed-off run is refused: it is the record of what somebody put their name to. Abandon a run you no longer want instead of deleting a signed one.

{
  "type": "object",
  "properties": {
    "run": {
      "type": "string",
      "maxLength": 200,
      "description": "The run id, e.g. RUN-2026-0001, or its title when only one carries it"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true. There is no undo and nothing is copied anywhere first"
    }
  },
  "required": [
    "run",
    "confirm"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn Pro on for this connection with key, an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "License key from checkout, MCPL1.<payload>.<signature>"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}